Skip to content

feat(engine): support map background colour#214

Merged
JumpLink merged 1 commit into
mainfrom
fix/map-background-color
Jun 12, 2026
Merged

feat(engine): support map background colour#214
JumpLink merged 1 commit into
mainfrom
fix/map-background-color

Conversation

@JumpLink

Copy link
Copy Markdown
Contributor

Problem

The mass-ported OoT2D-2014 maps (#212) showed a hard render defect: large void areas and 'strange artifacts'. Root cause: the original .zmap format carries a per-room background colour in its header — the 2014 game fills the whole screen with it before painting tiles, so sparse maps (Field stores tiles for only ~19% of its 372×380 cells) rely on it for the grass/floor. Our converter dropped it.

Changes

  • MapData.backgroundColor — optional #rrggbb, documented as a fill below all tile layers.
  • Engine: loadMap maps it onto the Excalibur GL clear colour (reset to transparent for maps without one). A colour Actor was tried first but goes through Excalibur's Rectangle Raster (2D-canvas rasterise + texture upload) — the clear colour is pure GL and matches the original game's fill-the-screen semantic.
  • MapPreview: fills the map bounds with the colour in both the direct paint and the baked texture — atlas cards + welcome thumbnails now show the real room colours.
  • Data: backgroundColor injected into all 19 games/oot2d-2014 maps from their zmap headers (exporter updated in PixelRPG/oot-2d@e3ea382; values range from Field's grass #409740 to SMB's classic sky #5C94FC).

Verification

  • Atlas previews verified visually (Field/Castle/Guards green, Deku brown, Lost Woods olive — matches the reference renders from tools/export-maps.py).
  • @pixelrpg/engine check + 748 tests green, @pixelrpg/gjs check green.
  • Engine-scene visual check pending a stable GL init — the intermittent engine-init segfault (pre-existing, see TODO) fired repeatedly during validation before any map code ran (Loading map: never logged), so it is unrelated to this change.

The 2014 zmap format fills each room with a header background colour
before painting tiles — the ported maps only stored the tiles, so
sparse maps (Field is ~19% tiles) rendered as void in the editor.

- MapData.backgroundColor (optional #rrggbb, below all layers)
- engine: map colour -> GL clear colour on loadMap (a colour Actor
  would raster through the 2D-canvas path; clear colour is pure GL
  and matches the original game's fill-the-screen semantic)
- MapPreview: fill the map bounds in the widget paint + the bake
- games/oot2d-2014: backgroundColor injected into all 19 maps from
  the zmap headers (exporter: PixelRPG/oot-2d e3ea382)
@JumpLink JumpLink merged commit a84c2c9 into main Jun 12, 2026
1 check passed
JumpLink added a commit that referenced this pull request Jun 12, 2026
…219)

No behaviour change — the preview/card pair grew through several
review iterations (#214-#218); this consolidates:

map-preview:
- constants moved above the class JSDoc so it documents the class
- cache key derived forward (_cacheKeyBase + _cacheKey()) instead of
  string-parsing the composed key backwards; the stored-key field is
  gone — _runBake computes the key when it stores
- _bakedCenter folded into _viewportBake (single last-viewport-bake
  record; _baked stays the is-current marker for both modes)
- _clampCenter takes the widget extent instead of a horizontal flag
- _populateFromMap renamed _setSource (no key parameter anymore)

scene-card:
- _moveDeltaInParent extracts the parent-space delta math that was
  duplicated between drag-update and drag-end
- _suppressTrailingClick extracts the idle-reset click suppression
  shared by drag-end and the lock-click handler
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant