Heresy: Add masked vehicle graphics for stages 1-6

[dpt]

Rename vehicle bitmap arrays to descriptive names, add masked variants for near-frame vehicle sprites across all stages (proper silhouette masking instead of solid rectangles), fix a corrupt perp car on the pregame screen exposed by the switch, and dedupe stage 6 vehicle graphics into CommonData.c.

Summary by Sourcery

Enable optional silhouette-masked near-frame vehicle rendering across stages 1–6 while consolidating shared graphics and improving bitmap tooling.

New Features:

• Add optional silhouette-masked near-frame vehicle graphics for vehicle sprites across stages 1–6.
• Extend the graphics sheet tooling to preserve and edit masked sprites, frame-major tables, and trailing scaffold bytes.

Bug Fixes:

• Render masked perp cars correctly on the pregame reveal screen, fixing the corrupt vehicle display exposed by masked graphics.
• Fix vehicle graphic export/import layout issues for special and padded bitmap data.

Enhancements:

• Rename stage vehicle bitmap arrays with descriptive vehicle names.
• Deduplicate shared stage 6 vehicle graphics into CommonData.c while retaining the existing unmasked fallback.

Build:

• Add the CHQ_ENABLE_MASKED_VEHICLES build option for enabling silhouette-masked vehicle rendering.

Documentation:

• Document the revised single-column graphics sheet layout and handling of masked, frame-major, and padded bitmap arrays.

[sourcery-ai]

Reviewer's Guide

Implements an optional CHQ_ENABLE_MASKED_VEHICLES build flag that replaces near-frame vehicle sprites in stages 1–6 with silhouette-masked variants, renames per-stage vehicle bitmap sets to descriptive names, deduplicates stage 6 vehicle graphics into CommonData.c, and fixes the perp car reveal on the pregame screen to use masked drawing when appropriate; also updates the PNG graphics tooling to correctly detect masked arrays across all stage data files.

Sequence diagram for masked pregame perp car reveal

sequenceDiagram
  participant Pregame as PregameScreen
  participant Reveal as reveal_perp_car
  participant Sprite as plot_masked_sprite_by_width
  participant Buffer as BackBuffer

  Pregame->>Reveal: reveal_perp_car
  Reveal->>Reveal: inspect BITMAPFLAG_MASKED
  alt masked vehicle bitmap
    Reveal->>Sprite: plot_masked_sprite_by_width
    Sprite->>Buffer: draw silhouette-masked sprite
  else default vehicle bitmap
    Reveal->>Buffer: plot_sprite
  end

Loading

File-Level Changes

Change	Details	Files
Add CHQ_ENABLE_MASKED_VEHICLES build-time option and propagate its compile definition to game and tests targets.	Introduce CHQ_ENABLE_MASKED_VEHICLES option in CMakeLists.txt with descriptive help text. Define CHQ_ENABLE_MASKED_VEHICLES for the ChaseHQ and ChaseHQ_Tests targets when the option is enabled.	C/CMakeLists.txt
Provide masked bitmap variants for common vehicle graphics (lambo, truck, sedan, perp cars, F40 etc.) and expose them via CommonData.h guarded by CHQ_ENABLE_MASKED_VEHICLES.	Add *_masked pixel_t arrays alongside existing vehicle-related bitmaps in CommonData.c, using doubled width and interleaved mask/data layout. Declare externs for all new *masked arrays in CommonData.h under #ifdef CHQ_ENABLE_MASKED_VEHICLES. Ensure masked variants exist for shared near-frame vehicle sprites used across multiple stages (e.g., bitmap_lambo{1,2,3}, truck, car, E97D/EA2B/EA77, C95E/CA12/CA62).	C/libraries/ChaseHQ/Data/CommonData.c C/libraries/ChaseHQ/Data/CommonData.h
Switch stages 1–5 vehicle bitmap tables to use descriptive names and conditionally reference masked variants for near-frame sprites when CHQ_ENABLE_MASKED_VEHICLES is enabled.	Rename stage1 vehicle bitmap arrays from generic truck/car names to stage1_pickup_bitmaps and stage1_sedan0_bitmaps and wire them into the stage1 struct. Wrap stage1 lambo/pickup/sedan bitmap_t entries with #ifdef CHQ_ENABLE_MASKED_VEHICLES to select BITMAPFLAG_MASKED and *_masked arrays for near frames; retain existing masked far-frame entries. In stage2, rename lods arrays to stage2_sedan2_bitmaps, stage2_sedan1_bitmaps, stage2_car_bitmaps and add stage2-specific masked pixel arrays for each, wiring them into the bitmap_t tables when CHQ_ENABLE_MASKED_VEHICLES is set. In stage3, rename lods to stage3_f40_bitmaps, stage3_convertible_bitmaps, stage3_sedan_bitmaps and hook up CommonData masked sedan bitmaps and stage3-local masked convertible bitmaps conditionally. In stage4, rename lods to stage4_blacksedan_bitmaps, stage4_sedan3_bitmaps, stage4_convertible_bitmaps and add masked variants for the stage4 vehicle sheets, then use them in bitmap_t tables when masking is enabled. In stage5, rename lods to stage5_lambo_bitmaps, stage5_pickup_bitmaps, stage5_f40_bitmaps and switch their near frames to CommonData masked arrays under CHQ_ENABLE_MASKED_VEHICLES.	C/libraries/ChaseHQ/Data/Stage1Data.c C/libraries/ChaseHQ/Data/Stage2Data.c C/libraries/ChaseHQ/Data/Stage3Data.c C/libraries/ChaseHQ/Data/Stage4Data.c C/libraries/ChaseHQ/Data/Stage5Data.c
Deduplicate stage 6 vehicle graphics by reusing CommonData lambo, pickup, and F40 bitmaps, with optional masked variants, instead of a local monolithic bitmap blob.	Remove the large stage6_bitmap_C960 pixel array and associated direct offsets for three vehicle types in Stage6Data.c. Rewrite stage6_veh1/veh2/veh3 bitmap_t tables to reference CommonData lambo/truck/F40 arrays and their masked counterparts under CHQ_ENABLE_MASKED_VEHICLES, preserving far-frame masked entries via CommonData (car_4, truck_4, CA89/CAA9).	C/libraries/ChaseHQ/Data/Stage6Data.c
Make the perp car pregame reveal respect masked sprites when the corresponding bitmap_t uses BITMAPFLAG_MASKED.	Extend reveal_perp_car in Main.c to branch on perp_bitmap->flags, calling plot_masked_sprite_by_width for BITMAPFLAG_MASKED instead of always using plot_sprite. Document that bitmaps_perp_car[0] shares data with in-race near-frame vehicle sprites and that masking must be consistent between reveal and race rendering.	C/libraries/ChaseHQ/Engine/Main.c
Update graphics_png.py tooling to correctly mark masked arrays by scanning all stage data files together for CommonData bitmap references.	Compute a combined all_text over every Stage*Data.c file and feed it to find_masked_array_names so maskedness detection sees references regardless of which file holds them. Merge main_masked_names with masked names from all data text before marking manifest entries as masked when width_bytes is even.	C/scripts/graphics_png.py

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[sourcery-ai]

Hey - I've reviewed your changes and they look great!

Sourcery assessment

Approved.

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}