Drop stale >512 tile chunk warnings (#213)

docs/tile-maps.md

@@ -122,8 +122,10 @@ Each chunk becomes one draw call. A tile can be any size and can be nudged
 off the grid (the platformer raises its grass tiles a few pixels so the
 player's feet line up with the art); a chunk's bitmap grows to fit.
 
-> **Keep `chunkSize` at 512 or below.** Larger chunks can fail to draw inside
-> a running game even though they work in isolation (issue #213).
+> **512 is a good `chunkSize`.** Larger chunks draw fine, but each chunk's
+> bitmap covers its whole bounding box, so tiles far apart in one chunk spend
+> texture memory on the empty space between them - and HD Roku devices have
+> only 64MB of it.
 
 Baking happens once, in `onCreate()`, so its cost is paid while the level
 loads rather than every frame.

examples/platformer/src/source/Entities/Level.bs

@@ -23,14 +23,9 @@ class Level extends BGE.GameEntity
   ' disk-sourced images, up to 16 simultaneous 320px blits/frame, sustained) found zero
   ' failures after that fix, versus the ~192px threshold before it.
   '
-  ' Still keep this well under 768: a merged chunk that spans a large mostly-empty vertical
-  ' gap (e.g. this level's floating one-way platform merging with unrelated ground tiles
-  ' far below it) can still silently fail to render at 768+ *inside this actual running
-  ' game* even though the identical dimensions render reliably in an isolated
-  ' rendererTest-style stress test (confirmed: a 512x325 chunk here renders fine; a 768x325
-  ' chunk, same height, does not) - a real, currently-unexplained difference between an
-  ' isolated blit and the full Game/GameScene/entity/collision pipeline - filed as issue #213
-  ' rather than chased further here.
+  ' 768 and 1024 render correctly too (issue #213: the chunk that used to vanish was culled
+  ' by its top-left corner, fixed in #258), but a bigger chunk that merges the floating
+  ' platform with the ground below it spends texture memory on the empty gap between them.
   private chunkSize = 512.0
 
   sub new(game as BGE.Game)

examples/rpg/src/source/World/TileMapEntity.bs

@@ -10,7 +10,7 @@ import "pkg:/source/engine/colliders/SolidWorld.bs"
 ' per tile), plus the solid tiles and map bounds added to the area's SolidWorld.
 class TileMapEntity extends BGE.GameEntity
 
-  ' Chunks >= 768px can fail to render inside a running game (issue #213), so stay at 512.
+  ' Bigger chunks draw fine (#213), but waste texture memory on empty space; 512 is plenty.
   private chunkSize = 512.0
   private regionCache as roAssociativeArray = {}
 

src/source/utils/tilemap/TileMapBaking.bs

@@ -42,22 +42,13 @@ namespace BGE.TileMap
   ' pushes it past a grid-aligned bucket boundary - it just makes that one chunk's bitmap a
   ' little larger than chunkSize, rather than losing part of the tile.
   '
-  ' A screen-aligned Image above ~192px used to silently fail to draw on both the
-  ' BrightScript Simulator and real hardware, even with fully correct content (confirmed
-  ' via GetByteArray/tmp:/ PNG round-trip) and a draw call reporting success - traced to
-  ' Renderer.render() never calling Finish() on its destination before the frame
-  ' proceeds (see Renderer.bs's own comment on that call, and issue #211). With that fixed,
-  ' chunkSize up to 512 has been confirmed reliable on real hardware (memory- and
-  ' disk-sourced images, up to 16 simultaneous 320px blits/frame, sustained). Still keep it
-  ' well under 768, though: a merged chunk spanning a large mostly-empty vertical gap (e.g.
-  ' a floating platform merged with unrelated ground tiles far below it) can still silently
-  ' fail to render at 768+ *inside a real running game* even though the identical
-  ' dimensions render reliably in an isolated stress test - see examples/platformer's
-  ' Level.bs for the specific confirmed-safe/confirmed-broken measurements and the
-  ' follow-up (issue #213) tracking this remaining gap.
+  ' 512 is a good chunkSize. Larger chunks draw correctly (1024 is confirmed on real
+  ' hardware), but a chunk's bitmap covers its whole bounding box, so tiles far apart in
+  ' one chunk (e.g. a floating platform and the ground below it) spend texture memory on
+  ' the empty space between them - and HD Roku devices have only 64MB of it.
   '
   ' @param {BGE.TileMap.TileSpec[]} tiles
-  ' @param {float} chunkSize - grouping granularity, in world pixels (keep <= 512)
+  ' @param {float} chunkSize - grouping granularity, in world pixels (512 recommended)
   ' @return {BGE.TileMap.BakedChunk[]}
   function bakeTileMapImages(tiles as BGE.TileMap.TileSpec[], chunkSize as float) as BGE.TileMap.BakedChunk[]
     tilesByChunk = {}