Add image overlay support to possession mode lenses by Cerwym · Pull Request #4506 · dkfans/keeperfx

Cerwym · 2026-01-26T08:28:24Z

Implements overlay image rendering for lens effects

Overlays can be used with mist / distortion effects, they will be rendered AFTER such and won't be affected

This PR also as per feedback has been extended to allow for support of loading both overlays and mist effects from data, and fxdata and will allow for fallback into the base game's directory too.

Here's a full mod proving the setup.
test-pr-4506.zip

Test Scenarios

Creature	Lens ID	Test Case	Expected Behavior
Bug	17	Mist from ZIP	Loads `mist_zip_test` from `lens_mists.zip`
Fly	18	Mist from data folder	Loads `mist_data_test.raw` from mod `data/`
Hell Hound	19	Overlay from ZIP	Loads `overlay_zip_test` from `lens_overlays.zip`
Spider	20	Overlay from data folder	Loads `overlay_data_test.raw` from mod `data/` (vertical blue stripes)
Tentacle	21	Mist fallback	Fails to find in ZIP, falls back to `mist_fallback_test.raw` in mod `data/`
Dragon	22	Overlay fallback	Fails to find in ZIP, falls back to `overlay_fallback_test.raw` in mod `data/` (checkerboard + red border)

Load Order Priority

The try_load_file_from_mods_with_fallback() helper function searches in this order:

Mod ZIP files - Check each enabled mod's ZIP archives (via JSON registry)
Mod data folders - Check each enabled mod's data/ or fxdata/ directories
Base game data - Fallback to core game data/ or fxdata/ folders
test-pr-4506.zip

Verification

To test, possess each creature in-game. Expected results:

Bug/Fly/Tentacle: Mist effects applied
Hell Hound: Overlay from ZIP visible
Spider: Blue vertical stripes overlay (pallete will render it as pink)
Dragon: Checkerboard pattern with red border overlay

Example of overlay and mist effect on a Dragon

Implements overlay image rendering for lens effects, allowing modders to add custom visual overlays (helmets, visors, HUD elements) during creature possession. Features: - RAW (256x256, 8-bit indexed) and PNG/BMP format support - Automatic mod directory detection and fallback to base game - Palette index 0 treated as transparent - Stretch-to-fit scaling for widescreen compatibility - Overlay configuration via lenses.cfg: Overlay = filename.raw alpha Files modified: - src/config_lenses.c/h: Configuration parsing and data structures - src/lens_api.c: Image loading and rendering implementation

Copilot

Pull request overview

Adds support for defining and rendering an image overlay as part of a lens effect, intended to be drawn on top of existing mist/distortion lens rendering (e.g., for helmet/visor visuals in possession mode).

Changes:

Extends LensConfig with overlay fields (file, mod dir, in-memory image buffer, dimensions, alpha).
Adds config parsing for a new OVERLAY directive in lenses.cfg.
Implements overlay loading (RAW + PNG/BMP) and overlay drawing in the lens render pipeline.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 7 comments.

File	Description
src/lens_api.c	Loads overlay images and draws them after other lens effects.
src/config_lenses.h	Extends `LensConfig` with overlay-related fields and adds `LCF_HasOverlay`.
src/config_lenses.c	Adds parsing support for `OVERLAY = <file> <alpha>` and tracks mod-relative paths.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

src/lens_api.c

src/config_lenses.c

benlp91 · 2026-01-26T20:23:31Z

Just let me know if I should test it

src/custom_sprites.c

…o feature/lens-overlay

benlp91 · 2026-01-27T12:30:38Z

I forgot how to trigger a Prototype lol @Loobinex please can you do?

PieterVdc · 2026-01-27T12:33:33Z

I forgot how to trigger a Prototype lol @Loobinex please can you do?

it just needed approval because Cerwym isn't maintainer

Cerwym · 2026-01-27T13:55:20Z

I forgot how to trigger a Prototype lol @Loobinex please can you do?

it just needed approval because Cerwym isn't maintainer

What with me being new and untrustworthy and all that

…ook at zip, then mod data, then core data in case of not finding the file

…tion - Created try_load_file_from_mods_with_fallback() helper function - Reduces code duplication for mod->base game file loading pattern - Applied to lens overlay loading as proof of concept - Helper function can be reused for other mod fallback scenarios

- Mist files now check mods' data directories before base game - Consistent mod fallback behavior between overlays and mists - Better logging to show which mod provided the mist file

…ence - Changed from checking fx_data flag to mod_dir flag (allows any mod directory) - Added LbFileExists() check before LbFileLoadAt() to avoid error spam - Fixes crash when loading files that don't exist in all mods - Prevents access violations from failed file loads

… code

src/config_lenses.h

Copilot

Pull request overview

Copilot reviewed 11 out of 12 changed files in this pull request and generated 9 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-01-30T19:12:29Z

src/config.c

+    // Set the terminator at the actual count position (not at max_count-1)
+    if (named_fields_set->names != NULL && named_fields_set->count_field != NULL)
+    {
+        named_fields_set->names[*named_fields_set->count_field].name = NULL;


parse_named_field_blocks() sets the terminator at names[*count_field], but names is only sized to max_count entries in callers (e.g., lenses_desc[LENS_ITEMS_MAX]). If a config defines block index max_count-1, count_field becomes max_count and this writes one past the end. Either allocate names arrays as max_count+1 (space for sentinel) or clamp the terminator write to max_count-1 and adjust semantics accordingly.

Suggested change

// Set the terminator at the actual count position (not at max_count-1)

if (named_fields_set->names != NULL && named_fields_set->count_field != NULL)

{

named_fields_set->names[*named_fields_set->count_field].name = NULL;

// Set the terminator safely within the allocated range

if (named_fields_set->names != NULL && named_fields_set->count_field != NULL)

{

int terminator_index = *named_fields_set->count_field;

if (terminator_index >= named_fields_set->max_count)

{

terminator_index = named_fields_set->max_count - 1;

}

named_fields_set->names[terminator_index].name = NULL;

src/lens_api.c

Copilot · 2026-01-30T19:12:30Z

src/lens_api.c


 void setup_eye_lens(long nlens)
 {
+    WARNLOG("CONFIG_DEBUG: setup_eye_lens called with nlens=%ld", nlens);


setup_eye_lens() currently logs "CONFIG_DEBUG" via WARNLOG on every invocation. Since this can happen frequently during play, please switch to SYNCDBG (or gate behind BFDEBUG_LEVEL) so release logs aren’t polluted with warning-level messages.

Copilot · 2026-01-30T19:12:30Z

src/lens_api.c

+        }
+
+        if (LbFileLoadAt(fname, cache->data) != size) {
+            WARNLOG("Failed to load overlay file '%s' from /data directory", lenscfg->overlay_file);


When loading a ".raw" overlay file, this code calls LbFileLoadAt() directly. LbFileLoadAt() reads the full file length into the buffer, so without checking LbFileLengthRnc(fname) first, an oversized file can overflow cache->data before the return-value check runs. Validate size (or reuse try_load_file_from_mods_with_fallback) before loading.

Copilot · 2026-01-30T19:12:31Z

src/thing_creature.c

+  // Apply lens effect to the viewport area only (not including sidebar)
+  draw_lens_effect(lbDisplay.WScreen + view_x, lbDisplay.GraphicsScreenWidth, 
+      scrmem + view_x, eye_lens_width, view_width, view_height, game.applied_lens_type);


draw_lens_effect() is applied only with a +view_x offset. If player->engine_window_y is ever non-zero (eg centered/shifted view), the lens effect will be applied to the wrong region and the buffer pointers will be incorrect. Include view_y and offset dst/src by (view_y * pitch) + view_x.

Copilot · 2026-01-30T19:12:31Z

src/config_lenses.c

+    SYNCLOG("value_overlay called: argnum=%d, value='%s', lens=%d", named_field->argnum, value_text, idx);
+
+    if (value_text == NULL || value_text[0] == '\0') {


value_overlay() uses SYNCLOG for routine parsing traces. This is very noisy during normal config loading; please switch these to SYNCDBG at an appropriate level (or remove once validated) so logs aren’t polluted in non-debug runs.

Copilot · 2026-01-30T19:12:31Z

src/config_lenses.h

 #endif
 /******************************************************************************/
-#define LENS_ITEMS_MAX 32
+#define LENS_ITEMS_MAX 255


Lenses are indexed starting at 1 (0 is the default entry), and get_lens_config() returns &lenses[lens_idx]. With LENS_ITEMS_MAX set to 255, the highest valid index is 254, but lenses_count can become 255 (from lens254) and an eye_effect of 255 would access lenses[255] out of bounds. If the intent is to support IDs up to 255, LENS_ITEMS_MAX should be 256 (or adjust indexing/count logic to keep indices < LENS_ITEMS_MAX).

Suggested change

#define LENS_ITEMS_MAX 255

#define LENS_ITEMS_MAX 256

src/custom_sprites.c

…o feature/lens-overlay

Cerwym mentioned this pull request Jan 26, 2026

Allow custom lens decals for a particular creature model #3793

Closed

Loobinex requested a review from PieterVdc January 26, 2026 09:59

PieterVdc requested a review from Copilot January 26, 2026 10:02

Copilot started reviewing on behalf of PieterVdc January 26, 2026 10:02 View session

Copilot AI reviewed Jan 26, 2026

View reviewed changes

Cerwym added 2 commits January 26, 2026 22:19

refactored to use json loading

dd22e83

added example mod for lens overlay

f35386e

Loobinex reviewed Jan 26, 2026

View reviewed changes

src/custom_sprites.c Outdated Show resolved Hide resolved

Loobinex and others added 5 commits January 26, 2026 23:34

Merge branch 'master' into pr/4506

03b31b7

changed load bit flags to descriptive enums

971e0cb

Merge branch 'feature/lens-overlay' of github.com:Cerwym/keeperfx int…

fd8420e

…o feature/lens-overlay

corrected render order of swipe effect and lenses

3af40d0

thing creature view now scales lens effect for viewport area correctly

11ce658

benlp91 linked an issue Jan 27, 2026 that may be closed by this pull request

Allow custom lens decals for a particular creature model #3793

Closed

benlp91 marked this pull request as draft January 27, 2026 12:29

benlp91 marked this pull request as ready for review January 27, 2026 12:29

benlp91 marked this pull request as draft January 27, 2026 12:29

PieterVdc marked this pull request as ready for review January 27, 2026 12:32

PieterVdc marked this pull request as draft January 27, 2026 12:32

Cerwym marked this pull request as ready for review January 27, 2026 13:54

Cerwym added 5 commits January 30, 2026 11:21

ci added properties json for vscode mingw intellisense

d65b056

feat allowe dfor custom lens mist effects, added logic to gracefull l…

3fe10b1

…ook at zip, then mod data, then core data in case of not finding the file

refactor: apply mod fallback helper to mist file loading

819f549

- Mist files now check mods' data directories before base game - Consistent mod fallback behavior between overlays and mists - Better logging to show which mod provided the mist file

Cerwym added 2 commits January 30, 2026 17:54

feat: added try_load_file_from_mods_with_fallback to consolidate load…

edb4221

… code

chore: log cleanup

008bda5

Loobinex marked this pull request as draft January 30, 2026 18:31

Loobinex marked this pull request as ready for review January 30, 2026 18:31

PieterVdc reviewed Jan 30, 2026

View reviewed changes

src/config_lenses.h Outdated Show resolved Hide resolved

fix: decoupled lens overlay data from save code

2e64ad5

PieterVdc requested a review from Copilot January 30, 2026 19:02

Copilot started reviewing on behalf of PieterVdc January 30, 2026 19:02 View session

Copilot AI reviewed Jan 30, 2026

View reviewed changes

Loobinex and others added 4 commits January 30, 2026 21:05

Some documentation.

bf1af73

fix magenta 255 is now the transparent colour

f1dc88b

Merge branch 'feature/lens-overlay' of github.com:Cerwym/keeperfx int…

c2b22fa

…o feature/lens-overlay

fix added pallete conversion when loading the pngs preserve greyscale

7ad9f6c

Loobinex marked this pull request as draft January 31, 2026 01:14

Cerwym added 2 commits January 31, 2026 09:41

fix clear mist flag and biffer if lens has no overlay

b4966e3

remove justlog

755f43f

Loobinex marked this pull request as ready for review January 31, 2026 13:24

Removed one more JUSTLOG

c8c9859

Loobinex merged commit 810ea10 into dkfans:master Jan 31, 2026

-    // Set the terminator at the actual count position (not at max_count-1)
-    if (named_fields_set->names != NULL && named_fields_set->count_field != NULL)
-    {
-        named_fields_set->names[*named_fields_set->count_field].name = NULL;
+    // Set the terminator safely within the allocated range
+    if (named_fields_set->names != NULL && named_fields_set->count_field != NULL)
+    {
+        int terminator_index = *named_fields_set->count_field;
+        if (terminator_index >= named_fields_set->max_count)
+        {
+            terminator_index = named_fields_set->max_count - 1;
+        }
+        named_fields_set->names[terminator_index].name = NULL;

		SYNCLOG("value_overlay called: argnum=%d, value='%s', lens=%d", named_field->argnum, value_text, idx);

		if (value_text == NULL \|\| value_text[0] == '\0') {

Conversation

Cerwym commented Jan 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Test Scenarios

Load Order Priority

Verification

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

benlp91 commented Jan 26, 2026

Uh oh!

Uh oh!

benlp91 commented Jan 27, 2026

Uh oh!

PieterVdc commented Jan 27, 2026

Uh oh!

Cerwym commented Jan 27, 2026

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Jan 30, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Copilot AI Jan 30, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 30, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 30, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 30, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 30, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Cerwym commented Jan 26, 2026 •

edited

Loading