Phobos-developers · CZHczhABCZ · Jun 27, 2026 · Jun 27, 2026 · Jun 28, 2026 · Jun 28, 2026
diff --git a/CREDITS.md b/CREDITS.md
@@ -878,3 +878,4 @@ This page lists all the individual contributions to the project by their author.
 - **Chang_zhi**:
   - Interop export interface for accessing scenario local/global variables
   - Add `ClampToScreen` tag for `BannerType` to control whether banner position is clamped to the visible area
+- **ABCZ (CZHczhABCZ)** - Passengers Cameo Display
diff --git a/Phobos.vcxproj b/Phobos.vcxproj
@@ -47,6 +47,7 @@
     <ClCompile Include="src\Commands\ToggleDigitalDisplay.cpp" />
     <ClCompile Include="src\Commands\ToggleMessageList.cpp" />
     <ClCompile Include="src\Commands\ToggleSWSidebar.cpp" />
+    <ClCompile Include="src\Commands\ToggleCameos.cpp" />
     <!-- src\Ext -->
     <!-- src\Ext\Aircraft -->
     <ClCompile Include="src\Ext\Aircraft\Body.cpp" />
@@ -310,6 +311,7 @@
     <ClInclude Include="src\Commands\ToggleDigitalDisplay.h" />
     <ClInclude Include="src\Commands\ToggleMessageList.h" />
     <ClInclude Include="src\Commands\ToggleSWSidebar.h" />
+    <ClInclude Include="src\Commands\ToggleCameos.h" />
     <!-- src\Ext -->
     <ClInclude Include="src\Ext\Aircraft\Body.h" />
     <ClInclude Include="src\Ext\Anim\Body.h" />

diff --git a/YRpp b/YRpp
diff --git a/docs/User-Interface.md b/docs/User-Interface.md
@@ -526,6 +526,59 @@ In `RA2MD.INI`:
 ShowPowerPlantEnhancerRange=false  ; boolean
 ```
 
+### Show Cameo
+
+- You can now configure the game to display cameo icons and their counts above a selected vehicle or building, showing both passengers (`Passengers=`) and garrisoned occupants (`Occupier=`). Only shown when a single unit is selected (not box-selection).
+- Two activation modes are available:
+  - **Permanent mode**: Set `ShowCameo=true` (globally or per-unit) to always display cameos. Per-unit setting overrides the global setting. If a per-unit `ShowCameo` is explicitly set to `false`, cameos are never shown for that unit.
+  - **Toggleable mode**: Set `ShowCameo=false` (global) and `ShowCameo.Toggleable=true` (global), then use the [Toggle Cameos](#toggle-cameos) hotkey to switch the display on/off. The master switch `ShowCameo.Enable` in `RA2MD.INI` controls the toggle state.
+- Cameos are arranged in horizontal rows, centered above the selection bracket. When the number of cameo types exceeds `ShowCameo.PerRow`, additional rows are stacked above the bottom row. The first-entered unit is displayed at the top.
+- Translucency can be set via `ShowCameo.Translucency` (0/25/50/75, default 0). SHP cameos are affected; PCX cameos are not.
+- `ShowCameo.OverlapXY` and `ShowCameo.OffsetXY` control overlap between adjacent cameos. `ShowCameo.OverlapPrimary` (default true) determines whether the earlier cameo covers the later one. On the same row, only X overlap applies; when wrapping to a new row, only Y overlap applies.
+- A custom cameo shape (SHP) can be specified per passenger/occupant type via `ShowCameo.CustomShape` in `artmd.ini`. Animated SHPs are supported. A custom PCX can be specified via `ShowCameo.CustomPCX`. A custom palette can be specified via `ShowCameo.CustomPalette`; if not set, the palette falls back to `CameoPalette` or the default `cameo.pal`.
+
+```{hint}
+For example, with `ShowCameo.PerRow=1` (vertical stacking), `ShowCameo.OverlapPrimary=true` means the bottom cameo covers the one above it, preserving the bottom cameo's text label from being hidden.
+```
+
+- When toggled via the hotkey, messages are shown from CSF labels `MSG:ShowCameoEnabled` (fallback: "Cameos Display: Enabled") and `MSG:ShowCameoDisabled` (fallback: "Cameos Display: Disabled").
+
+In `RA2MD.INI`:
+```ini
+[Phobos]
+ShowCameo.Enable=true               ; boolean
+```
+
+In `rulesmd.ini`:
+```ini
+[AudioVisual]
+ShowCameo=false                     ; boolean
+ShowCameo.Toggleable=false          ; boolean
+ShowCameo.PerRow=5                  ; integer
+ShowCameo.BottomOffset=0,0          ; X,Y
+ShowCameo.Translucency=0            ; translucency level (0/25/50/75)
+ShowCameo.OverlapXY=0,0             ; X,Y overlap percentage
+ShowCameo.OffsetXY=0,0              ; X,Y pixel offset
+ShowCameo.OverlapPrimary=true       ; boolean
+
+[SOMETECHNO]                        ; TechnoType
+ShowCameo=                          ; boolean, default true
+ShowCameo.PerRow=                   ; integer, defaults to [AudioVisual]
+ShowCameo.BottomOffset=             ; X,Y, defaults to [AudioVisual]
+ShowCameo.Translucency=             ; translucency level (0/25/50/75), defaults to [AudioVisual]
+ShowCameo.OverlapXY=                ; X,Y, defaults to [AudioVisual]
+ShowCameo.OffsetXY=                 ; X,Y, defaults to [AudioVisual]
+ShowCameo.OverlapPrimary=           ; boolean, defaults to [AudioVisual]
+```
+
+In `artmd.ini`:
+```ini
+[SOMETECHNO]                        ; TechnoType
+ShowCameo.CustomShape=              ; SHP filename
+ShowCameo.CustomPCX=                ; PCX filename
+ShowCameo.CustomPalette=            ; PAL filename
+```
+
 ## Hotkey Commands
 
 ### `[ ]` Display Damage Numbers
@@ -585,6 +638,11 @@ For this command to work in multiplayer - you need to use a version of [YRpp spa
 - Deselect 1 or 5 object(s) from current selected objects.
 - For localization add `TXT_DESELECT`, `TXT_DESELECT_DESC`, `TXT_DESELECT5` and `TXT_DESELECT5_DESC` into your `.csf` file.
 
+### `[ ]` Toggle Cameos
+
+- Switches on/off [cameo display](#show-cameo) in toggleable mode. Has no effect in permanent mode.
+- For localization add `TXT_SHOWCAMEO` and `TXT_SHOWCAMEO_DESC` into your `.csf` file.
+
 ## Loading screen
 
 - PCX files can now be used as loadscreen images.

diff --git a/docs/Whats-New.md b/docs/Whats-New.md
@@ -607,6 +607,7 @@ HideShakeEffects=false           ; boolean
 - [Customize the step limit of the credits indicator](User-Interface.md#customize-the-step-limit-of-the-credits-indicator) (by Noble_Fish)
 - [Disable the credits indicator smooth transition](User-Interface.md#disable-the-credits-indicator-smooth-transition) (by Noble_Fish)
 - Add `selling`, `undeploying` and `harvesting` conditions to `DiscardOn` (by Noble_Fish)
+- [Show Cameo feature to display passenger/occupant cameos above selected vehicles/buildings](User-Interface.md#show-cameo) (by ABCZ)
 
 #### Vanilla fixes:
 - Fixed sidebar not updating queued unit numbers when adding or removing units when the production is on hold (by CrimRecya)

diff --git a/src/Commands/Commands.cpp b/src/Commands/Commands.cpp
@@ -14,6 +14,7 @@
 #include "ToggleMessageList.h"
 #include "DeselectObject.h"
 #include "DeselectObject5.h"
+#include "ToggleCameos.h"
 
 #include <CCINIClass.h>
 
@@ -32,6 +33,7 @@ DEFINE_HOOK(0x533066, CommandClassCallback_Register, 0x6)
 	MakeCommand<ToggleSWSidebar>();
 	MakeCommand<DeselectObjectCommandClass>();
 	MakeCommand<DeselectObject5CommandClass>();
+	MakeCommand<ToggleCameosCommandClass>();
 
 	if (Phobos::Config::SuperWeaponSidebarCommands)
 	{

diff --git a/src/Commands/ToggleCameos.cpp b/src/Commands/ToggleCameos.cpp
@@ -0,0 +1,54 @@
+#include "ToggleCameos.h"
+
+#include <Utilities/GeneralUtils.h>
+#include <Ext/Rules/Body.h>
+#include <MessageListClass.h>
+#include <HouseClass.h>
+
+const char* ToggleCameosCommandClass::GetName() const
+{
+	return "Toggle Cameos";
+}
+
+const wchar_t* ToggleCameosCommandClass::GetUIName() const
+{
+	return GeneralUtils::LoadStringUnlessMissing("TXT_SHOWCAMEO", L"Toggle Cameos");
+}
+
+const wchar_t* ToggleCameosCommandClass::GetUICategory() const
+{
+	return CATEGORY_INTERFACE;
+}
+
+const wchar_t* ToggleCameosCommandClass::GetUIDescription() const
+{
+	return GeneralUtils::LoadStringUnlessMissing("TXT_SHOWCAMEO_DESC", L"Show/hide cameo display.");
+}
+
+void ToggleCameosCommandClass::Execute(WWKey eInput) const
+{
+	// Ignore hotkey in permanent mode
+	if (RulesExt::Global()->ShowCameo)
+		return;
+
+	// Ignore hotkey if toggleable is off
+	if (!RulesExt::Global()->ShowCameo_Toggleable)
+		return;
+
+	Phobos::Config::ShowCameo_Enable = !Phobos::Config::ShowCameo_Enable;
+
+	auto PrintMessage = [](const wchar_t* pMessage)
+	{
+		MessageListClass::Instance.PrintMessage(
+			pMessage,
+			RulesClass::Instance->MessageDelay,
+			HouseClass::CurrentPlayer->ColorSchemeIndex,
+			true
+		);
+	};
+
+	if (Phobos::Config::ShowCameo_Enable)
+		PrintMessage(GeneralUtils::LoadStringUnlessMissing("MSG:ShowCameoEnabled", L"Cameos Display: Enabled"));
+	else
+		PrintMessage(GeneralUtils::LoadStringUnlessMissing("MSG:ShowCameoDisabled", L"Cameos Display: Disabled"));
+}
diff --git a/src/Commands/ToggleCameos.h b/src/Commands/ToggleCameos.h
@@ -0,0 +1,13 @@
+#pragma once
+
+#include "Commands.h"
+
+class ToggleCameosCommandClass : public CommandClass
+{
+public:
+	virtual const char* GetName() const override;
+	virtual const wchar_t* GetUIName() const override;
+	virtual const wchar_t* GetUICategory() const override;
+	virtual const wchar_t* GetUIDescription() const override;
+	virtual void Execute(WWKey eInput) const override;
+};
diff --git a/src/Ext/Rules/Body.cpp b/src/Ext/Rules/Body.cpp
@@ -453,6 +453,15 @@ void RulesExt::ExtData::LoadBeforeTypeData(RulesClass* pThis, CCINIClass* pINI)
 	this->AutoRemoveEarliestBeacon.Read(exINI, GameStrings::General, "AutoRemoveEarliestBeacon");
 	this->AllowBeaconHotKeyInSinglePlayer.Read(exINI, GameStrings::General, "AllowBeaconHotKeyInSinglePlayer");
 
+	this->ShowCameo.Read(exINI, GameStrings::AudioVisual, "ShowCameo");
+	this->ShowCameo_Toggleable.Read(exINI, GameStrings::AudioVisual, "ShowCameo.Toggleable");
+	this->ShowCameo_PerRow.Read(exINI, GameStrings::AudioVisual, "ShowCameo.PerRow");
+	this->ShowCameo_BottomOffset.Read(exINI, GameStrings::AudioVisual, "ShowCameo.BottomOffset");
+	this->ShowCameo_Translucency.Read(exINI, GameStrings::AudioVisual, "ShowCameo.Translucency");
+	this->ShowCameo_OverlapXY.Read(exINI, GameStrings::AudioVisual, "ShowCameo.OverlapXY");
+	this->ShowCameo_OffsetXY.Read(exINI, GameStrings::AudioVisual, "ShowCameo.OffsetXY");
+	this->ShowCameo_OverlapPrimary.Read(exINI, GameStrings::AudioVisual, "ShowCameo.OverlapPrimary");
+
 	// Section AITargetTypes
 	int itemsCount = pINI->GetKeyCount("AITargetTypes");
 	for (int i = 0; i < itemsCount; ++i)
@@ -804,6 +813,14 @@ void RulesExt::ExtData::Serialize(T& Stm)
 		.Process(this->SecondaryFireSequenceLandOnly)
 		.Process(this->AutoRemoveEarliestBeacon)
 		.Process(this->AllowBeaconHotKeyInSinglePlayer)
+		.Process(this->ShowCameo)
+		.Process(this->ShowCameo_Toggleable)
+		.Process(this->ShowCameo_PerRow)
+		.Process(this->ShowCameo_BottomOffset)
+		.Process(this->ShowCameo_Translucency)
+		.Process(this->ShowCameo_OverlapXY)
+		.Process(this->ShowCameo_OffsetXY)
+		.Process(this->ShowCameo_OverlapPrimary)
 		;
 }
 

diff --git a/src/Ext/Rules/Body.h b/src/Ext/Rules/Body.h
@@ -384,6 +384,15 @@ class RulesExt
 		Valueable<bool> AutoRemoveEarliestBeacon;
 		Valueable<bool> AllowBeaconHotKeyInSinglePlayer;
 
+		Valueable<bool> ShowCameo;
+		Valueable<bool> ShowCameo_Toggleable;
+		Valueable<int> ShowCameo_PerRow;
+		Valueable<Point2D> ShowCameo_BottomOffset;
+		TranslucencyLevel ShowCameo_Translucency;
+		Valueable<Point2D> ShowCameo_OverlapXY;
+		Valueable<Point2D> ShowCameo_OffsetXY;
+		Valueable<bool> ShowCameo_OverlapPrimary;
+
 		ExtData(RulesClass* OwnerObject) : Extension<RulesClass>(OwnerObject)
 			, Storage_TiberiumIndex { -1 }
 			, HarvesterDumpAmount { 0.0f }
@@ -708,6 +717,15 @@ class RulesExt
 			, AutoRemoveEarliestBeacon { false }
 
 			, AllowBeaconHotKeyInSinglePlayer { false }
+
+			, ShowCameo { false }
+			, ShowCameo_Toggleable { false }
+			, ShowCameo_PerRow { 5 }
+			, ShowCameo_BottomOffset { { 0, 0 } }
+			, ShowCameo_Translucency { 0 }
+			, ShowCameo_OverlapXY { { 0, 0 } }
+			, ShowCameo_OffsetXY { { 0, 0 } }
+			, ShowCameo_OverlapPrimary { true }
 		{ }
 
 		virtual ~ExtData() = default;
+0 −2		BeaconManagerClass.h
+0 −12		EventClass.h
+0 −16		IPXManagerClass.h
+0 −44		SessionClass.h
+0 −4		UI.h
+0 −7		Unsorted.h
+1 −4		WWMouseClass.h
+0 −3		WinsockInterfaceClass.h