Tilemap JavaScript per giochi 2D: griglia, tileset e collisioni

Documentazione – BeeEngine

v2.10.4

BeeTilemap — Documentazione Tecnica

Griglia di celle: 0 vuoto, solidi, tileset 1-based

📁 Panoramica

BeeTilemap è una griglia di celle. Estende BeeEntity. Vive in src/graphics/BeeTilemap.js. 0 è vuoto: non si disegna e non è mai solido. Gli id in solidTiles sono muri. Il pathfinder li legge con isSolidTile dopo useTilemap.

Il tileset è 1-based: la cella 1 è il primo riquadro dell’immagine (tile - 1). Senza tileset i muri sono #666 e le altre celle #999. rows e cols seguono tiles: cols è la riga più lunga.

const map = new BeeTilemap({ tileSize: 32, tiles: [ [1, 1, 1], [0, 0, 0], [2, 2, 2] ], solidTiles: [2] }); gioco.addEntity(map);

📁 Celle

L’origine della griglia è worldX / worldY. Una cella mancante vale 0. Fuori mappa, getTile torna null.

1. misura getWorldAABB è tutta la mappa. Vuota, o tileSize non valido: lati 0. Il culling non usa il 32×32 dell’entità.
2. solidi entityCollides guarda ogni cella coperta dal collider. Il bordo destro e quello basso non entrano nella tile dopo.
3. drawSolo le celle nella view. Con tileset, drawImage. Senza, un rettangolo. Il fillStyle non resta nel contesto.

📁 Dove è facile sbagliare

0 non è un muro. Anche se lo metti in solidTiles, isSolidTile lo tratta come vuoto. Il primo grafico del tileset è l’id 1, non 0.

La collisione non parte da sola. Il loop non chiama entityCollides. Serve un collider con width e height sopra 0. Un box che finisce esattamente sul bordo di una tile solida, senza entrarci, non collide. Il pathfinder usa isSolidTile, non questo metodo.

Righe storte. Se una riga è più corta, le celle che mancano sono 0. Sostituisci tiles e rows / cols si aggiornano. Il pathfinder copia le misure in useTilemap: dopo un cambio di mappa va richiamato.

📁 Esempio: tileset e un collider

map.tileset = img; map.tilesetColumns = 8; if (map.entityCollides(hero)) { hero.vx = 0; }

Senza ctx, o con tileSize / tilesetColumns non finiti o ≤ 0, draw esce e non chiama drawImage.

📁 Riepilogo API

Sul pass mondo, insieme alla camera. tileSize di default è 32. tilesetColumns di default è 1.

Membro	Ritorna	Scopo
`new BeeTilemap({ x, y, tiles, tileSize, solidTiles, tileset, tilesetColumns }?)`	`BeeTilemap`	Griglia in `x, y`. `tiles` è `number[][]`, riga per riga.
`rows` / `cols`	number	Seguono `tiles`. `cols` è la riga più lunga.
`getWorldAABB()`	`{ x, y, width, height }`	Tutta la mappa. Vuota o `tileSize` non valido: lati 0.
`getTile(col, row)`	number / `null`	Fuori mappa: `null`. Cella mancante o `undefined`: `0`.
`worldToTile(px, py)` / `isSolidAtPixel(px, py)`	cella / boolean	Pixel mondo rispetto a `worldX` / `worldY`.
`isSolidTile(col, row)`	boolean	`0`, `null` e le celle fuori sono vuote. Il resto è solido se sta in `solidTiles`.
`entityCollides(entity)`	boolean	Senza collider, o con lati `≤ 0`: false. Copre le tile del rettangolo. Il bordo destro e basso è escluso.
`draw(ctx, engine?)`		Celle visibili. Senza `ctx`, o con misure non valide: return. `visible === false`: return.