Webový editor úrovní

V tomto editoru scén a úrovní pro picogame můžeš přímo v prohlížeči importovat PNG se sprity a sadami dlaždic, kreslit dlaždicové mapy, označovat význam dlaždic (solid, coin, goal, hazard) a umisťovat sprity, popisky HUDu, zóny, výchozí body a částice. Můžeš také nastavit kameru sledující hráče a uložit celou hru jako jeden game.json, který deska spustí přímo. Umí také importovat mapy z editoru Tiled.

Plátno představuje výřez světa, který může být větší než obrazovka zařízení. Editor proto slouží pro úrovně na jednu obrazovku i pro posouvané mapy.

Open the level editoropens on its own page · paint tiles, place sprites, build scrolling maps, save one game.json · your session autosaves in this browser

Tlačítko výše otevře editor na samostatné stránce. Rozdělaná práce se automaticky ukládá do prohlížeče (localStorage), takže návrat nebo omylem obnovená stránka pokračuje tam, kde jsi skončil — Save zapíše game.json (do zvolené složky, nebo ke stažení) — pod jménem souboru, který jsi otevřel, nebo pod tím, které zvolí Save as…. Při prvním spuštění se ukáže krátká úvodní karta; klávesou ? kdykoli zobrazíš přehled zkratek.

Zdrojový kód: tools/editor/ — statická aplikace bez backendu. Naklonuj a spusť python3 -m http.server -d tools/editor, nebo si ji hostuj sám (GitHub Pages stačí); node test.js spustí její headless testy.

Import mapy z Tiled

Kreslíš mapy radši v Tiled? Open načte mapu z Tiled přímo: vyber .tmx/.tmj soubor spolu s jeho tilesety (.tsx/.tsj) a PNG obrázky v jednom multi-výběru souborů (prohlížeč neumí následovat cesty). Co se převede:

dlaždicové vrstvy → vrstvy tilemapy; flipnuté/otočené dlaždice se stanou nativními orientacemi
tile objekty → sprity (rotace → angle, custom properties → data); obdélníky → zóny, pointy → pointy (custom properties jdou s nimi)
bool vlastnosti dlaždic (solid, coin, goal, hazard, …) → příznaky dlaždic
tilesety se zkompaktní jen na dlaždice, které mapa používá (buňka enginu je jeden bajt → až 253 různých dlaždic na tileset)

Nepodporované věci z Tiled (animované dlaždice, sub-tile kolize, image vrstvy, opacity/tint/parallax, polygonové objekty, infinite/izometrické mapy) nástroj vypíše, nikdy tiše nezahodí. Stejný převod existuje i jako CLI nástroj — tools/tiled2scene.py — pro offline pipeline; viz formát scény.

▶ Try in playground spustí úroveň v prohlížeči i s opravdovou grafikou: editor rovnou převede každý importovaný PNG do PAL8 formátu enginu (stejná pravidla jako při převodu pro zařízení — max. 255 barev, alfa < 128 = průhledná), takže vidíš přesně to, co vykreslí handheld.

Začni ukázkovou úrovní

Menu Demos v horní liště načte hotové úrovně. Otevři jednu a podívej se, jak má nastavené položky World size a Camera:

Sample (one screen) — kompaktní úroveň na jednu obrazovku s ukázkou všech funkcí.
Scrolling platformer (bounded) — svět 960×240 (~3 obrazovky široký). Sledovací kamera na ose x omezenou na rozměry světa, takže se na levém a pravém okraji zastaví.
Open world (bigger both ways) — mapa 640×480, větší než obrazovka v obou směrech. Kamera sleduje hráče po osách xy, takže se můžeš pohybovat vodorovně i svisle.

Úvodní karta odkazuje na stejné dvě ukázky posouvaných map.

Velikost světa a obrazovky

V panelu Level jsou dvě důležité velikosti. Panel uvidíš s nástrojem Select, když není nic vybrané:

World size — jak velká je celá úroveň, v pixelech. Tady nastavíš velikost úrovně: je to rozměr světa, od kterého se odvozují meze kamery, funkce Fit, minimapa a velikost nových vrstev. Vedle hodnoty vidíš také přibližný počet obrazovek „≈ N × M“.
Device screen — jedna obrazovka zařízení (320×240), označená na plátně přerušovaným bílým rámečkem.

Pro posouvanou úroveň nastav World size větší než jednu obrazovku.

Jak vytvořit posouvanou úroveň

V panelu Level (nástroj Select, nic vybráno) nastav World size větší než jedna obrazovka: napiš world w×h a zvol Apply world size, nebo použij některou předvolbu: 1 screen, 3× wide (plošinovka), 2×2 screens (otevřený svět). Editor nabídne zvětšit/oříznout vrstvy tilemapy, aby ho vyplnily.
Vyber nástroj Paint a sadu dlaždic (PNG nebo + Colour tileset). Nová vrstva vyplní celý svět. Pohled posuneš tažením se stisknutou klávesou Space, prostředním tlačítkem nebo nástrojem Pan. K orientaci slouží minimapa vpravo nahoře; Fit zobrazí celý svět a 100% vrátí měřítko 1:1.
Nástrojem Place umísti sprite — importuj PNG, nebo klikni + Colour sprite pro barevný placeholder blok (bez grafiky; hrdina v ukázkách je přesně tohle) — a jeden pojmenuj player (Select → pole name).
V Select nastav Camera → follow → player. Meze kamery ve výchozím nastavení odpovídají World size (auto); odškrtnutím můžeš táhnout vlastní oranžový rámeček camera-bounds.
Save zapíše game.json a grafiku .pal8, kterou čte deska — viz tabulka níže. Když chceš jednu úroveň předpečenou, Build ▾ → Baked module dá <name>_scene.py připravený pro picogame_scene.load(pg, level1_scene.SCENE), se všemi importovanými PNG zapečenými do PAL8 přímo v prohlížeči (žádný Python krok).

Změna World size (nebo velikosti jedné vrstvy v panelu Paint) při zvětšení doplní prázdné dlaždice, při zmenšení ořízne a nejdřív se zeptá, pokud by se ztratily namalované. Vše lze vzít zpět (Ctrl+Z). Nastavení Layer size použij, když má být vrstva menší než svět nebo posunutá kvůli paralaxnímu efektu. Ve většině úrovní stačí měnit World size.

Nástroje a ovládání

Nástroj	Klávesa	Co dělá
Select	1 / V	Vybere a přesune objekt. Opakovaný klik na stejné místo prochází překrývající se objekty. Upravuje také příznaky a barvu dlaždice.
Paint	2 / B	Maluje aktivní vrstvu. Táhnutí = štětec, Shift-táhnutí = obdélník, Alt-klik = výplň.
Place	3 / P	Umístí vybraný sprite.
HUD	4	Popisek s pevnou polohou na obrazovce; spravuje i vrstvy částic.
Zone	5	Vytvoří tažením spouštěcí oblast, kterou můžeš pojmenovat.
Point	6	Pojmenovaný bod (např. `spawn`).
Pan	H / Space	Posun pohledu (posouvá i prostřední tlačítko).

Kolečko posouvá pohled, Ctrl/⌘+kolečko mění měřítko kolem kurzoru, stejně jako +/−. Klávesa F zobrazí celý svět. Šipky posouvají výběr (Shift = ×10) nebo posouvají pohled, když nic není vybráno. Ctrl+Z/Y zpět/vpřed, Ctrl+C/V/D kopírovat/vložit/duplikovat, Delete smaže, Esc zruší výběr. Pravý panel se mění podle aktivního nástroje, takže vidíš jen potřebné ovládání. Běžné hlášky přicházejí jako mizející toasty; dialog prohlížeče se objeví jen tam, kde by klik něco zničil (New, Open přes neuloženou práci, smazání vymalované vrstvy), nebo kde je potřeba jméno (Save as…).

Kreslení grafiky přímo v editoru

Každý asset má tlačítko ✎ a panely Paint a Place nabízejí ✎ Paint a sprite / ✎ Paint tiles pro prázdný (16×16, u sady osm dlaždic). Pixelový editor má tužku, plechovku, gumu, kapátko a zpět; paleta začíná barvami, které grafika už používá, a jakákoli další je na jeden klik. Vícesnímková grafika se kreslí po snímcích.

Není tam žádné vyhlazování ani částečná průhlednost, protože je nemá ani deska: pixel je barva, nebo je průhledný (šachovnice). Co nakreslíš, se zapíše zpátky jako PNG toho assetu, takže Save z něj upeče .pal8 úplně stejně jako z importované grafiky — včetně zápisu rovnou na desku.

Příznaky dlaždic

Příznak dává dlaždici význam, který čte hra, ale nemění její vzhled. Načítání scény připraví vyhledávací tabulky, takže herní kód nemusí pracovat s pevně zadanými čísly dlaždic:

flag	hra to čte jako	typické použití
solid	`view.is_solid(tx, ty)`	zdi / podlaha blokující pohyb
coin	`view.tile_has(tx, ty, "coin")`	sběratelný předmět, hra ho po sebrání odebere
goal	`view.tile_has(tx, ty, "goal")`	východ z úrovně / cílová dlaždice
hazard	`view.tile_has(tx, ty, "hazard")`	láva / bodliny, co zraní hráče

Každý asset má tlačítko ⬇, které ho stáhne jako PNG strip (snímky zleva doprava, dlaždice 0 = prázdná) — stejný formát, jaký editor importuje. U barevného tilesetu nebo placeholder spritu se strip vygeneruje za běhu, takže si můžeš vzít „spritesheet“ ukázkové úrovně, v grafickém editoru přes něj namalovat vlastní grafiku se zachovaným pořadím snímků a znovu ho importovat: každá dlaždice, kterou úroveň používá, dál funguje.

Přepínačem Show flag badges on map v panelu Paint zapneš barevné značky v rozích dlaždic. Volba Paint → + Colour tileset vytvoří jednoduchou barevnou sadu bez obrázků. Barvy upravíš výběrem barvy a další přidáš pomocí + add colour.

Jedna hra, jeden soubor

Všechno, co editor čte nebo zapisuje, je jeden z těchhle souborů. Tučně je tlačítko.

soubor	co je uvnitř	kdo ho upravuje
`game.json` — Save	celá hra: všechny úrovně (mapy jako řádky ASCII), tabulka prostředků (jména, velikosti dlaždic, příznaky, legendy — nikdy pixely), zvuky, příběhy zón, efekty	ty v editoru, agent v textovém editoru, `scene_build.py fmt`. Jediný soubor, který je hra
`hero.png`, `tiles.png`	tvoje grafika, na kterou se `game.json` odkazuje jménem	ty v grafickém editoru. Importované PNG editor zkopíruje do složky
`hero.pal8`, `tiles.pal8` — Save (do složky) nebo Build → Art	tatáž grafika upečená pro desku: malá hlavička, paleta, bajt na pixel	nikdo. Odvozené z PNG, přepisované při každé změně
`story.py`	příběhové skripty `def name(d)`, na které se zóna odkáže přes `{"script": "name"}`	ty nebo agent, v Pythonu. Editor ho jen čte
`code.py`	hra: runner, který playground ukáže po Try in playground, je dobrý začátek	ty nebo agent
`<name>_scene.py` — Build → Baked module	jedna úroveň upečená jako modul Pythonu (grafika uvnitř)	nikdo. Pro desku bez loaderu `game.json`; plnou cestu pro ship dělá `scene_build.py build --mpy`

Open bere game.json (vyber k němu PNG, soubory .pal8 a story.py, nebo měj zvolenou složku a načtou se samy), starší scene.json / project.json / .pgproj.json i mapu z Tiled. Staré soubory se při příštím Save vrátí jako projekt game.json; nic se neztratí. Úroveň otevřená z balíčku pro desku, kde je jen grafika .pal8, ukáže obnovené pixely (565 barev, tvrdá alfa) a funguje stejně jako s PNG.

Rozdělaná práce se dál ukládá do prohlížeče, takže omylem obnovená stránka pokračuje tam, kde jsi byl — pravdou je ale soubor na disku: se zvolenou složkou se změna, která se tam objeví (třeba od agenta), do dvou sekund znovu načte, pokud tu nemáš nic neuloženého, a jinak ti to editor ohlásí.

Spuštění na zařízení nebo v simulátoru

Save ▾ → Save to board… zkopíruje soubory za tebe: jednou vybereš připojený disk CIRCUITPY a editor tam zapíše game.json, .pal8 ke každému PNG assetu, story.py a — pokud tam už jeden není, který by přepsal — runner code.py vybraný podle toho, jakou úroveň jsi postavil. Nejdřív zkontroluje boot_out.txt (to je to, co dělá ze složky CircuitPython desku) a upozorní, když v lib/ není žádný picogame_*. CircuitPython se sám znovu načte, takže hra běží dřív, než pustíš myš. (Chrome nebo Edge; ostatní prohlížeče mají cestu se stažením níže.)

Ručně jsou to tytéž soubory. Deska čte game.json sama. Zkopíruj složku na CIRCUITPY — game.json, soubory .pal8, story.py, code.py — a hra nastartuje z textového souboru: každá úroveň se upeče při startu (40–60 ms na RP2040) a JSON můžeš upravit přímo na disku a stisknout reset.

python3 tools/scene_build.py check      # před kopírováním: id, legendy, zóny, efekty, odkazy na skripty
python3 tools/scene_build.py art        # PNG -> .pal8 (Save to dělá také, když je zvolená složka)
python3 tools/scene_build.py build --mpy   # ship: build/ s game_bank.mpy + level_*.mpy + code.py

Build vymění jeden řetězec v code.py — z Game(pg, "game.json") je Game(pg, "game_bank") — a tatáž hra běží z kompaktních modulů jen s aktuální úrovní v RAM. Oba pekaři (prohlížeč i nástroj) zapisují bajtově shodné soubory .pal8, takže nezáleží na tom, který běžel naposled. API loaderu popisuje formát scény.

Otevření úrovně, kterou upravoval někdo jiný

Open bere jakýkoli game.json, nejen ten, který editor sám uložil: ručně upravený, změněný agentem, stažený z desky. Vrstvy, příznaky dlaždic, zóny, výchozí body, efekty i kamera se vrátí editovatelné; legenda, kterou agent pro řádky mapy zvolil, zůstává, a neznámé klíče projdou nedotčené.

Když upravujete oba naráz:

Se zvolenou složkou si editor změny game.json na disku všimne do dvou sekund. Nemáš tu nic neuloženého → načte ji a řekne to. Máš → řekne ti to jednou a Save se před přepsáním zeptá.
V gitu je jeden řádek mapy jeden řádek souboru, takže agentův nový strop a tvoje překreslená podlaha se slijí bez konfliktu. Kolidují jen úpravy téhož řádku, a pak editor ukáže na konfliktní značky místo chyby parsování.

Ukládání do adresáře projektu (místo stahování)

📁 Folder… v hlavičce se jednou zeptá na složku (Chrome/Edge) a od té chvíle Save zapisuje přímo do ní: game.json, .pal8 vedle každého PNG prostředku, zdrojové PNG, které ve složce chybí, a story.py, pokud panel Story ještě drží starší těla skriptů a story.py neexistuje. Bez složky se všechno stahuje: game.json přes Save, soubory .pal8 přes Build → Art.

Díky tomu je úroveň něco, na čem můžete pracovat s agentem společně: editor zapisuje tentýž soubor, který agent čte, v repozitáři, kde hra žije.

ASCII mapy — level čitelný v diffu

Tilemapy se ukládají jako jeden řetězec na řádek nad legendou, která patří k tilesetu:

"assets": { "tiles": { "type": "tileset", "src": "tiles.png", "tile": [16, 16],
                       "legend": { ".": 0, "#": 1, "o": 2 } } },
...
{ "kind": "tilemap", "asset": "tiles", "rows": ["....o....", "..####...", "#########"] }

Legenda jen roste: poprvé namalovaná dlaždice dostane další volný znak a znak, který se už používá, si drží význam přes každé uložení — diff mapy tak zůstává obrázkem a písmena, která jsi zvolil ty nebo agent, přežijí. Dlaždice s překlopením nebo otočením má vlastní znak; vrstva s více různými dlaždicemi, než abeceda unese (91), zůstane u číselné mřížky.

Dvě chyby, které může udělat ruční úprava, a kde se chytí: znak mimo legendu se upeče jako prázdná dlaždice a řádky různé délky udělají mapu neobdélníkovou — obojí ohlásí scene_build.py check, než se cokoli dostane na desku.

Spolupráce s AI agentem

Jeden soubor, žádný generovaný kód a stejné nástroje pro oba:

Ty: jednou zvol 📁 Folder…, aby editor zapisoval do repozitáře, postav úroveň, Save.
Agent: upravuje game.json — řádky mapy, pozice objektů, zóny a jejich příběhová data, efekty — a story.py / code.py. Před předáním pustí scene_build.py check a fmt, po změně PNG art. Nikdy nesahá na soubory .pal8 ani na nic v build/.
Ty: změna se v editoru objeví sama (zvolená složka) nebo v git diff jako obrázek. Upravuj dál, Save, opakuj.
Ship přes scene_build.py build --mpy, až je hra hotová; při ladění běží deska přímo z game.json.

Předání hry agentovi přes chat místo složky je tentýž soubor: přilož game.json (a story.py), grafika cestuje jednou.