Gestione Collectible Canvas JS: Pickups, Physics e World Space

Documentazione – BeeEngine

v2.8.1

BeeCollectible — Documentazione Tecnica

Bonus che cade: reset / collect, moto su worldY

📁 Panoramica

BeeCollectible è un item che cade. Vive in src/gameplay/BeeCollectible.js, estende BeeEntity. Non è un collider, non è uno score manager, non è un pool. Cade a speed costante sullo asse mondo; se passa sotto canvasHeight si ritela in cima (reset). Se lo raccogli chiami collect(collector): parte onCollect, poi destroy() (release se è pooled).

Quello che non è: un pickup automatico. La scena deve vedere l’overlap (demo: collisions.overlap('player', 'loot', …)) e chiamare collect. value è solo un numero: a incrementare lo score ci pensa onCollect (o tu).

v2.8.1: collect, moto su worldY, gravity/vx/vy a zero così integrate() non lo sposta. Test in scripts/test-beecollectible.mjs.

import { BeeEngine, BeeCollectible, BeePlayer } from ‘beeengine’; const item = new BeeCollectible(800, 600, null, 20, 20, 1, (it, who) => { if (who.addScore) who.addScore(it.value); }); // nella scena, dopo collisions.run() / overlap: if (player.collidesWith(item)) item.collect(player);

📁 Due uscite: caduta e collect

Non sono la stessa cosa. Sotto lo schermo si ritela. Collect toglie l’entity (o la rimette nel pool).

1. cadeworldY += speed * dt. Early-return se destroyed o inactive.
2a. fondoSe worldY > canvasHeight → reset() (x random, y = -height, speed 100–250).
2b. collectonCollect(this, collector) poi destroy(). No-op se spento. Non ritela.

Il costruttore azzera gravity, vx, vy. Il moto è solo speed: super.update chiama integrate() ma con quei tre a zero non aggiunge spostamento. Con un parent, worldY e y differiscono: il test lo copre, usa sempre il mondo.

📁 Scena, collisioni, prefab

La demo examples/demo.js mette l’item nel gruppo loot e fa:

game.collisions.overlap(‘player’, ‘loot’, (p, item) => { if (item && typeof item.collect === ‘function’) item.collect(p); });

Il prefab di stock 'collectible' costruisce così: canvas dal motore se manca, textureKey ?? sprite, value ?? score ?? 1, onCollect opzionale. Non è gioco.spawn (quello è il pool).

📁 Pool

BeeEntity.destroy con item.pool fa pool.release. Il pool in #sleep chiama recycle() (hook vuoto: oggi non c’è stato volatile) e in acquire chiama item.reset() se non hai passato un reset al BeePool. Quindi: collect → release → prossimo acquire ritela in cima.

📁 Dove è facile sbagliare

collect non è un reset. Sotto lo schermo l’item ricompare. Raccoglilo e sparisce (o torna a dormire nel pool). La demo ha un solo collectible: dopo il pickup è finito, a meno di acquire / new di nuovo.

Nessun auto-pickup. Senza overlap o collidesWith + collect, cade e basta. Ladybug può colorarlo di rosso (AABB) senza che sia raccolto.

value non incrementa lo score. È un campo. onCollect deve chiamare collector.addScore(item.value) (come la demo) o fare altro.

Canvas size è del costruttore. canvasWidth/Height non seguono un resize successivo. Il prefab legge engine.canvas solo allo spawn.

Non rimettere gravity / vy. Il costruttore li azzera apposta. Se li riscrivi, integrate() si somma a speed: di nuovo il doppio moto.

📁 Esempio: prefab + overlap

const gioco = new BeeEngine(‘testCanvas’, 800, 600); const item = gioco.prefabs.spawn(‘collectible’, { value: 5, onCollect: (it, who) => who.addScore(it.value) }); gioco.collisions.setGroup(‘loot’, [item]); gioco.collisions.overlap(‘player’, ‘loot’, (p, it) => it.collect(p));

📁 Riepilogo API

Costruttore posizionale (non un options bag): canvas, texture, size, value, onCollect. Fluent non c’è: i metodi di vita tornano undefined tranne quelli ereditati da BeeEntity.

Membro	Ritorna	Scopo
`new BeeCollectible(cw, ch, textureKey?, w?, h?, value?, onCollect?)`	`BeeCollectible`	Default 800×600, 20×20, value 1. Azzera gravity/vx/vy e chiama `reset()`.
`value` / `onCollect`	`number` / fn o null	Ricompensa e hook. Lo score lo fai tu nell’hook.
`speed`	`number`	Pixel/secondo. `reset` la randomizza 100–250.
`canvasWidth` / `canvasHeight`	`number`	Bound di spawn e di “sotto lo schermo”. Fissi al `new`.
`reset()`	—	`worldX` random, `worldY = -height`, nuova speed.
`collect(collector)`	—	No-op se destroyed / inactive. Altrimenti `onCollect(this, collector)` e `destroy()`.
`update(dt, input, engine)`	—	Early-return se spento. Cade in `worldY`, reset se sotto, poi `super.update`.
`recycle()`	—	Hook pool in `#sleep`. Vuoto: `reset` sta in `acquire`.
`draw(ctx, engine)`	—	Texture da `engine.getAsset(textureKey)` o cerchio arancione axis-aligned.
`prefabs.spawn('collectible', spec)`	istanza	value / score, onCollect, sprite / textureKey. Canvas dal motore se manca.