Add Passengers/Occupants Cameo Display by CZHczhABCZ · Pull Request #2272 · Phobos-developers/Phobos

CZHczhABCZ · 2026-06-27T13:25:33Z

Perhaps my inspiration came from a YR-based mod called Extreme Starry, but regardless, this feature provides players with a more convenient way to view the passengers inside vehicles.

When you select a single vehicle or building, cameo icons and counts of passengers/occupants inside are displayed above the unit, giving you a quick overview of what's inside. Two activation modes are available:

Permanent mode: Set ShowCameo=true (globally or per-unit) to always display cameos.
Toggleable mode: Set ShowCameo=false (global) + ShowCameo.Toggleable=true (global), then use the Toggle Cameos hotkey to switch the display on/off.

Features

Supports two unit types: passengers (Passengers) and garrisoned occupants (Occupant)
Only shown when a single unit is selected (not box-selection)
Layout: horizontal rows, fixed bottom boundary, auto wrap upward when exceeding PerRow, first-entered unit displayed at the top.
Example: A–E (letters represent entry order), 2 icons per row:
AB
CD
E (centered)
(bottom)
Translucency: set ShowCameo.Translucency = 0/25/50/75, SHP only
Overlap customization:
ShowCameo.OverlapXY: overlap percentage between adjacent cameos (supports negative values)
ShowCameo.OffsetXY: pixel offset adjustment (supports negative values)
ShowCameo.OverlapPrimary: controls overlay direction, true = earlier cameo covers later, false = later covers earlier
Custom SHP support:
ShowCameo.CustomShape in artmd.ini to specify a per-unit custom SHP icon (animated SHPs supported)
ShowCameo.CustomPalette to specify a custom palette; falls back to CameoPalette or the default cameo.pal

New INI Tags:

In RA2MD.INI:

[Phobos]
ShowCameo.Enable=true               ; boolean, master switch

In rulesmd.ini:

[AudioVisual]
ShowCameo=false                     ; boolean, permanent display
ShowCameo.Toggleable=false          ; boolean, allow hotkey toggle
ShowCameo.PerRow=5                  ; integer, max icons per row
ShowCameo.BottomOffset=0,0          ; X,Y, bottom boundary offset
ShowCameo.Translucency=0            ; 0/25/50/75, default 0 (opaque)
ShowCameo.OverlapXY=0,0             ; X,Y overlap percentage
ShowCameo.OffsetXY=0,0              ; X,Y pixel offset
ShowCameo.OverlapPrimary=true       ; boolean, earlier covers later

[SOMETECHNO]                        ; TechnoType
ShowCameo=                          ; boolean, default true
ShowCameo.PerRow=                   ; inherits [AudioVisual]
ShowCameo.BottomOffset=             ; inherits [AudioVisual]
ShowCameo.Translucency=             ; inherits [AudioVisual]
ShowCameo.OverlapXY=                ; inherits [AudioVisual]
ShowCameo.OffsetXY=                 ; inherits [AudioVisual]
ShowCameo.OverlapPrimary=           ; inherits [AudioVisual]

In artmd.ini:

[SOMETECHNO]                        ; TechnoType (passenger/occupant type)
ShowCameo.CustomShape=              ; SHP filename, uses default if not set
ShowCameo.CustomPCX=                ; PCX filename, uses default if not set
ShowCameo.CustomPalette=            ; PAL filename, falls back if not set

CSF Entries:

CSF Label	Description	Fallback Text
TXT_SHOWCAMEO	Hotkey name	Toggle Cameos
TXT_SHOWCAMEO_DESC	Hotkey description	Show/hide cameo display.
MSG:ShowCameoEnabled	Toggle enabled message	Cameos Display: Enabled
MSG:ShowCameoDisabled	Toggle disabled message	Cameos Display: Disabled

Fallback text is used if the CSF label is not found.

- Show passenger cameo icons and counts above vehicles when selected - Toggle via hotkey Toggle Unit Passengers with CSF-configurable messages - Two modes: Permanent (ShowUnitPassengers=true) and Toggleable (ShowUnitPassengers.Toggleable=true) - Icons use CAMEO_PAL, arranged bottom-to-top with fixed bottom boundary New INI tags: [AudioVisual] ShowUnitPassengers, ShowUnitPassengers.Toggleable, ShowUnitPassengers.EnabledMessage, ShowUnitPassengers.DisabledMessage [TechnoType] ShowPassengers, ShowPassengers.Toggleable, Passengers.PerRow, Passengers.BottomOffset

github-actions · 2026-06-27T15:11:57Z

Nightly build for this pull request:

compiled-dll-e82a38c7f0c578d4b7f06fe76d9a6c4a0ef4bbee.zip
These artifacts will expire in 90 days and will not be available for download after that time.

This comment is automatic and is meant to allow guests to get latest nightly builds for this pull request without registering. It is updated on every successful build.

NetsuNegi · 2026-06-27T22:53:43Z

I think this should be T1 level...
The new class is just for hotkey, there's no new-systems or large codes.

TaranDahl · 2026-06-28T01:55:42Z

I think this should be T1 level... The new class is just for hotkey, there's no new-systems or large codes.

I raised the level because she is a first-time contributor.

phoboscn-bot · 2026-06-28T02:28:54Z

To Chinese users:
This pull request has been mentioned on Phobos CN. There might be relevant details there:

致中文用户：
此拉取请求已在 Phobos CN 上被提及。那里可能有相关详细信息：

https://www.phoboscn.top/t/topic/600/1

NetsuNegi · 2026-06-28T03:05:42Z

I think this is should be T1 level...

I think this should be T1 level... The new class is just for hotkey, there's no new-systems or large codes.

I raised the level because she is a first-time contributor.

This is not appropriate.

- Show passenger cameo icons (SHP/PCX) and counts above vehicles when selected - Toggle via hotkey Toggle Unit Passengers with CSF-configurable messages - Two modes: Permanent (ShowUnitPassengers=true) and Toggleable (ShowUnitPassengers.Toggleable=true) - Icons use CAMEO_PAL/SHP, with PCX cameo fallback, arranged bottom-to-top with fixed bottom boundary New INI tags: [AudioVisual] ShowUnitPassengers, ShowUnitPassengers.Toggleable [TechnoType] ShowPassengers, ShowPassengers.PerRow, ShowPassengers.BottomOffset

CZHczhABCZ · 2026-06-28T03:55:31Z

Here are the additional test items.
https://www.phoboscn.top/t/topic/600/2?u=abcz

- Move ToggleUnitPassengers include and MakeCommand to end of lists - Place CameoPCX.Read before AltCameoPCX.Read per Ares convention - Cache bottomOffset.Get() to avoid repeated calls - Remove redundant passengerCounts.empty() check (already guards on NumPassengers)

DeathFishAtEase · 2026-06-28T10:31:22Z

To testers: At the current stage, the following need to be tested:

How it works when the transport is a BuildingType (Especially in terms of the coordinates drawn.).
How it works with unloading and loading passengers in different orders, continuously or at once (NoQueueUpToEnter).
How it interacts with the Automatic passenger deletion feature.

- Rename fallback strings to 'Unit Passenger Icons' per review feedback - Merge three Whats-New lines into one summary line with anchor link

…ngelog New features belong in Changelog > #### New:, not Breaking changes

…omOffset, fix display order and screen bounds

…ules/Body.h

…etail to Passengers Display section

CZHczhABCZ · 2026-07-04T06:37:19Z

@TaranDahl I think I've addressed all the changes you requested. Could you please re‑review?

(Ah…I hope this doesn't interfere with your normal work. Please feel free to re‑review whenever it's convenient for you.)

…lds to end of blocks in TechnoType

Move ShowPassengers_Enable as master switch with early return; merge redundant shouldShow branches; move CameoPalette.LoadFromINI after ShowPassengers reads to match declaration order

CSF: MSG:PassengerCameoDisplayEnabled/Disabled, TXT_PASSENGERCAMEO/_DESC. Fix passenger vector reversal for LIFO list. Docs: section title, description text, INI defaults.

…ottom) ordering

- Rename TogglePassengers to ToggleCameos - Add ShowCameo.CustomPalette tag (artmd.ini) - Fix building passenger display order (LIFO reverse + Y flip) - Fix occupant display order (FIFO, no reverse) - Update docs with full CN/EN bilingual documentation

…ix formatting - Move ShowCameo.Enable to its own [Phobos] block in Show Cameo section - Rewrite Show Cameo docs to be concise, English-only, following Phobos style - Remove Chinese from comments in Body.Visuals.cpp - Remove blank line before CameoPalette in TechnoType/Body.cpp - Fix ; placement in serialization chain

…rrectly with Y flip - When OverlapPrimary=true, earlier (visual top) cameos should cover later (visual bottom) ones - For buildings, the Y flip reverses visual order but draw order still followed cameoCounts - Fix: draw buildings in reverse cameoCounts order so visual top draws last

- Move Toggle Cameos to end of Hotkey Commands section - Move ShowCameo changelog entry from Breaking changes to New features - Move ShowCameo declarations to end of public block in Rules/Body.h - Restore blank line before BuildingSelectBracketPosition in Enum.h - Move ShowCameo_Enable to end of Config struct in Phobos.h - Move ShowCameo_Enable fields to end of Config blocks in Phobos.INI.cpp - Move ToggleCameos files to end of Commands block in Phobos.vcxproj

…-New - Move Toggle Cameos to after Deselect Object(s), before Loading screen - Remove ShowCameo.Enable from New user settings (0.2 version log) - Remove duplicate ShowCameo entry from Vanilla fixes (already in New section)

…New.md

…s-display

TaranDahl · 2026-07-08T08:25:39Z

+In `artmd.ini`:
+```ini
+[SOMETECHNO]                        ; TechnoType
+ShowCameo.CustomShape=              ; SHP filename
+ShowCameo.CustomPalette=            ; PAL filename
+```


No CustomPCX？

Oh wow, that makes sense... I forgot again. Something like a banner, hmm — yes, we do need support for custom PCX.

But WAIT…
The purpose of custom shapes is simply to expand the ways mods can display passengers or occupants. For example, an SHK could show a lightning bolt icon or animation, and a YURI could show a small mind-control icon or animation... So just custom SHP support might already be sufficient for these needs. As for custom PCX, I haven't yet figured out how it could be used.

As for custom PCX, I haven't yet figured out how it could be used.

Any difference with the CameoPCX?

[SOMETECHNO] ; TechnoType ShowCameo.CustomShape= ; SHP filename ShowCameo.CustomPCX= ; PCX filename ShowCameo.CustomPalette= ; PAL filename

It has been added…But I haven't tested whether it works properly (I think it should).

CZHczhABCZ force-pushed the feat-unit-passengers-display branch from c1aba96 to 5e17992 Compare June 27, 2026 13:59

TaranDahl added ❓New feature Needs testing ⚙️T2 T2 maintainer review is sufficient labels Jun 27, 2026

TaranDahl requested changes Jun 27, 2026

View reviewed changes

Comment thread docs/User-Interface.md Outdated

Comment thread docs/User-Interface.md Outdated

Comment thread docs/User-Interface.md Outdated

Comment thread src/Ext/Techno/Body.Visuals.cpp

TaranDahl reviewed Jun 27, 2026

View reviewed changes

Comment thread docs/User-Interface.md Outdated

TaranDahl reviewed Jun 27, 2026

View reviewed changes

Comment thread src/Ext/Techno/Body.Visuals.cpp Outdated

CZHczhABCZ force-pushed the feat-unit-passengers-display branch from 1bfa9f5 to 5d6ddbc Compare June 27, 2026 15:58

NetsuNegi added ⚙️T1 T1 maintainer review is sufficient and removed ⚙️T2 T2 maintainer review is sufficient labels Jun 27, 2026

CZHczhABCZ force-pushed the feat-unit-passengers-display branch 2 times, most recently from 34bec10 to bdedc8c Compare June 28, 2026 01:12

CZHczhABCZ force-pushed the feat-unit-passengers-display branch 2 times, most recently from 1d133f4 to 8fac7ff Compare June 28, 2026 03:31

CZHczhABCZ force-pushed the feat-unit-passengers-display branch from 8fac7ff to 1f1f0db Compare June 28, 2026 03:32

DeathFishAtEase reviewed Jun 28, 2026

View reviewed changes

CZHczhABCZ added 2 commits June 28, 2026 17:18

docs: refine documentation formatting per review

acf66e8

CZHczhABCZ and others added 3 commits June 28, 2026 18:57

docs: update CSF fallback text and shorten Whats-New entry

929925e

- Rename fallback strings to 'Unit Passenger Icons' per review feedback - Merge three Whats-New lines into one summary line with anchor link

[doc] Correct the writing of Changelog

833bc82

docs: move unit passengers display entry from Breaking changes to Cha…

7e442ae

…ngelog New features belong in Changelog > #### New:, not Breaking changes

CZHczhABCZ added 4 commits June 28, 2026 21:31

style: add blank lines between unrelated declarations and calls

ee05b3a

style: fix whitespace in Rules/Body.cpp

074849c

Merge upstream/develop into feat-unit-passengers-display

c2314d0

refactor: rename UnitPassengers to Passengers, add global PerRow/Bott…

801330c

…omOffset, fix display order and screen bounds

CZHczhABCZ changed the title ~~Add Unit Passengers Display~~ Add Passengers Cameo Display Jul 4, 2026

CZHczhABCZ added 2 commits July 4, 2026 14:25

docs: rename Icons to Cameos, merge CSF messages, fix dirty diff in R…

04e0649

…ules/Body.h

docs: split Toggle Passengers into standard format, add CSF message d…

35a61cd

…etail to Passengers Display section

CZHczhABCZ added 4 commits July 4, 2026 15:09

refactor: rename Passengers.Enable to ShowPassengers.Enable, move fie…

2b7b980

…lds to end of blocks in TechnoType

Fix ShowPassengers logic priority and CameoPalette INI reading order

0900197

Move ShowPassengers_Enable as master switch with early return; merge redundant shouldShow branches; move CameoPalette.LoadFromINI after ShowPassengers reads to match declaration order

Rename CSF labels to PassengerCameoDisplay, fix icon layout order

a2bf97b

CSF: MSG:PassengerCameoDisplayEnabled/Disabled, TXT_PASSENGERCAMEO/_DESC. Fix passenger vector reversal for LIFO list. Docs: section title, description text, INI defaults.

Fix passenger cameo layout: correct X (left-to-right) and Y (top-to-b…

6cf1934

…ottom) ordering

TaranDahl approved these changes Jul 4, 2026

View reviewed changes

DeathFishAtEase reviewed Jul 4, 2026

View reviewed changes

Comment thread docs/User-Interface.md Outdated

CZHczhABCZ added 6 commits July 5, 2026 22:45

fix: update changelog entry name and anchor to Show Cameo

54f9776

CZHczhABCZ changed the title ~~Add Passengers Cameo Display~~ Add Passengers/Occupants Cameo Display Jul 8, 2026

CZHczhABCZ added 7 commits July 8, 2026 14:41

docs: fix Occupier INI tag reference in Show Cameo section

d00b4f5

Merge upstream/develop: resolve conflict in Whats-New.md

e8f1a88

fix: reorder ShowCameo entry after upstream DiscardOn entry in Whats-…

e19bb92

…New.md

Merge branch 'feat-passengers-cameo-display' into feat-unit-passenger…

2518c80

…s-display

fix: remove duplicate DiscardOn entry, place ShowCameo at end

5fad5fc

docs: use cameo.pal instead of CAMEO_PAL for readability

3e4230a

Merge branch 'feat-passengers-cameo-display' into feat-unit-passenger…

fa96886

…s-display

TaranDahl reviewed Jul 8, 2026

View reviewed changes

feat: add ShowCameo.CustomPCX support for custom PCX cameo icons

6c9ed24

Uh oh!

Uh oh!

Conversation

CZHczhABCZ commented Jun 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Features

New INI Tags:

CSF Entries:

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actions Bot commented Jun 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

NetsuNegi commented Jun 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

TaranDahl commented Jun 28, 2026

Uh oh!

phoboscn-bot commented Jun 28, 2026

Uh oh!

NetsuNegi commented Jun 28, 2026

Uh oh!

CZHczhABCZ commented Jun 28, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

DeathFishAtEase commented Jun 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

CZHczhABCZ commented Jul 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

TaranDahl Jul 8, 2026

Choose a reason for hiding this comment

Uh oh!

CZHczhABCZ Jul 8, 2026

Choose a reason for hiding this comment

Uh oh!

TaranDahl Jul 8, 2026

Choose a reason for hiding this comment

Uh oh!

CZHczhABCZ Jul 9, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

CZHczhABCZ commented Jun 27, 2026 •

edited

Loading

github-actions Bot commented Jun 27, 2026 •

edited

Loading

NetsuNegi commented Jun 27, 2026 •

edited

Loading

DeathFishAtEase commented Jun 28, 2026 •

edited

Loading

CZHczhABCZ commented Jul 4, 2026 •

edited

Loading