### Complete Plugin Example: Enable Extra Cheats (C++)

Source: https://context7.com/nsgomez/gzcom-dll/llms.txt

This C++ code demonstrates a complete GZCOM DLL plugin that enables the game's debug functionality on startup. It defines a custom director class inheriting from cRZCOMDllDirector and overrides PreAppInit to access the application and enable debug features. It requires the GZCOM DLL SDK headers.

```cpp
#include "cIGZApp.h"
#include "cIGZFrameWork.h"
#include "cISC4App.h"
#include "cRZCOMDllDirector.h"

static const uint32_t kExtraCheatsDirectorID = 0x8bbd9623;
static const uint32_t kGZIID_cISC4App = 0x26ce01c0;

class cExtraCheatsDirector : public cRZCOMDllDirector {
public:
    // Resolve virtual method ambiguity
    bool QueryInterface(uint32_t riid, void** ppvObj) override {
        return cRZCOMDllDirector::QueryInterface(riid, ppvObj);
    }

    uint32_t AddRef() override { return cRZCOMDllDirector::AddRef(); }
    uint32_t Release() override { return cRZCOMDllDirector::Release(); }

    uint32_t GetDirectorID() const override {
        return kExtraCheatsDirectorID;
    }

    bool PreAppInit() override {
        cIGZFrameWork* pFramework = RZGetFrameWork();
        if (pFramework) {
            cIGZApp* pApp = pFramework->Application();
            if (pApp) {
                cISC4App* pISC4App = nullptr;
                if (pApp->QueryInterface(kGZIID_cISC4App, (void**)&pISC4App)) {
                    // Enable all debug/cheat functionality
                    pISC4App->SetDebugFunctionalityEnabled(true);
                    pISC4App->Release();
                }
            }
        }
        return true;
    }

    bool OnStart(cIGZCOM* pCOM) override {
        cIGZFrameWork* pFramework = RZGetFrameWork();
        if (pFramework) {
            // Handle both early and late loading
            if (pFramework->GetState() < cIGZFrameWork::kStatePreAppInit) {
                pFramework->AddHook(this);
            } else {
                PreAppInit();
            }
        }
        return true;
    }
};

// Required: Export the director
cRZCOMDllDirector* RZGetCOMDllDirector() {
    static cExtraCheatsDirector sDirector;
    return &sDirector;
}

```

--------------------------------

### Implement and Register cIGZSystemService (C++)

Source: https://context7.com/nsgomez/gzcom-dll/llms.txt

The cIGZSystemService interface is for services that provide functionality and receive tick/idle callbacks. Services must be registered with the framework and can be retrieved by other directors. This example shows a basic service implementation with initialization, shutdown, tick, and idle callbacks.

```cpp
#include "cIGZSystemService.h"
#include "cRZBaseSystemService.h"

static const uint32_t kMyServiceID = 0xABCDEF01;
static const int32_t kMyServicePriority = 1000;

class cMyService : public cRZBaseSystemService {
public:
    cMyService() : cRZBaseSystemService(kMyServiceID, kMyServicePriority) {}

    // Called for service initialization
    bool Init() override {
        return true;
    }

    // Called before service shutdown
    bool Shutdown() override {
        return true;
    }

    // Called on each game tick when registered with AddToTick
    bool OnTick(uint32_t dwTimeElapsed) override {
        // Perform periodic work
        return true;
    }

    // Called during idle time when registered with AddToOnIdle
    bool OnIdle(uint32_t dwUnknown) override {
        // Perform background work
        return true;
    }
};

// Register the service with the framework
cIGZFrameWork* pFramework = RZGetFrameWork();
cMyService* pService = new cMyService();

// Add to framework's service registry
pFramework->AddSystemService(pService);

// Enable tick callbacks
pFramework->AddToTick(pService);

// Enable idle callbacks
pFramework->AddToOnIdle(pService);

// Later: Remove from tick/idle and unregister
pFramework->RemoveFromTick(pService);
pFramework->RemoveFromOnIdle(pService);
pFramework->RemoveSystemService(pService);

```

--------------------------------

### Framework Hooks: cIGZFrameWorkHooks - Lifecycle Event Handling

Source: https://context7.com/nsgomez/gzcom-dll/llms.txt

The cIGZFrameWorkHooks interface allows plugins to respond to various stages of the SimCity 4 framework's lifecycle. Implementing these virtual methods enables precise control over initialization, shutdown, and event handling during game execution. The example illustrates how to register these hooks within the plugin's OnStart method and handle different framework states.

```cpp
#include "cIGZFrameWorkHooks.h"

class cIGZFrameWorkHooks : public cIGZUnknown {
public:
    // Called before framework initialization
    virtual bool PreFrameWorkInit(void) = 0;

    // Called before application initialization
    virtual bool PreAppInit(void) = 0;

    // Called after application initialization - safe to access game systems
    virtual bool PostAppInit(void) = 0;

    // Called before application shutdown
    virtual bool PreAppShutdown(void) = 0;

    // Called after application shutdown
    virtual bool PostAppShutdown(void) = 0;

    // Called after all system services are shut down
    virtual bool PostSystemServiceShutdown(void) = 0;

    // Called when the game terminates abnormally
    virtual bool AbortiveQuit(void) = 0;

    // Called during installation mode
    virtual bool OnInstall(void) = 0;
};

// Example: Register hooks in OnStart
bool OnStart(cIGZCOM* pCOM) override {
    cIGZFrameWork* pFramework = RZGetFrameWork();
    if (pFramework) {
        // Check framework state to handle late loading
        if (pFramework->GetState() < cIGZFrameWork::kStatePreAppInit) {
            pFramework->AddHook(this);
        } else {
            // Already past init phase, call directly
            PreAppInit();
            PostAppInit();
        }
    }
    return true;
}
```

--------------------------------

### GZCOM Base Interface: cIGZUnknown - Reference Counting and QueryInterface

Source: https://context7.com/nsgomez/gzcom-dll/llms.txt

The fundamental GZCOM interface, cIGZUnknown, provides essential COM functionalities like reference counting (AddRef, Release) and interface casting (QueryInterface). This allows dynamic querying and management of object interfaces within the SimCity 4 GZCOM system. The example demonstrates casting a generic application pointer to a specific cISC4App interface.

```cpp
#include "cIGZUnknown.h"

class cIGZUnknown {
public:
    // Cast to a different interface using its ID
    virtual bool QueryInterface(uint32_t riid, void** ppvObj) = 0;

    // Add a reference to this object
    virtual uint32_t AddRef(void) = 0;

    // Remove a reference (deletes object when count reaches zero)
    virtual uint32_t Release(void) = 0;
};

// Example: Casting an application pointer to SC4App interface
static const uint32_t kGZIID_cISC4App = 0x26ce01c0;

cIGZApp* pApp = pFramework->Application();
cISC4App* pISC4App = nullptr;

if (pApp->QueryInterface(kGZIID_cISC4App, (void**)&pISC4App)) {
    // Successfully cast to cISC4App
    pISC4App->SetDebugFunctionalityEnabled(true);
    // Don't forget to release when done
    pISC4App->Release();
}
```

--------------------------------

### Plugin Director: cRZCOMDllDirector - SimCity 4 Mod Base Class

Source: https://context7.com/nsgomez/gzcom-dll/llms.txt

cRZCOMDllDirector serves as the base class for creating SimCity 4 DLL plugins. It manages plugin initialization, lifecycle hooks, and object registration. Developers extend this class to define their mod's behavior, including handling game events and interacting with the framework. The example shows a basic plugin director implementation with a unique ID and lifecycle hook registration.

```cpp
#include "cRZCOMDllDirector.h"
#include "cIGZFrameWork.h"

// Unique ID for your plugin - generate a random 32-bit integer
static const uint32_t kMyPluginDirectorID = 0x12345678;

class cMyPluginDirector : public cRZCOMDllDirector {
public:
    // Required: Return your unique director ID
    uint32_t GetDirectorID() const override {
        return kMyPluginDirectorID;
    }

    // Called when the plugin is loaded
    bool OnStart(cIGZCOM* pCOM) override {
        // Register for framework hooks to receive lifecycle events
        cIGZFrameWork* pFramework = RZGetFrameWork();
        if (pFramework) {
            pFramework->AddHook(static_cast<cIGZFrameWorkHooks*>(this));
        }
        return true;
    }

    // Called after the application is fully initialized
    bool PostAppInit() override {
        // Safe to access game systems here
        return true;
    }

    // Called before application shutdown
    bool PreAppShutdown() override {
        // Clean up resources here
        return true;
    }
};

// Export your director - the game calls this function
cRZCOMDllDirector* RZGetCOMDllDirector() {
    static cMyPluginDirector sDirector;
    return &sDirector;
}
```

--------------------------------

### Access and Manage cIGZFrameWork Services and Hooks (C++)

Source: https://context7.com/nsgomez/gzcom-dll/llms.txt

The cIGZFrameWork interface serves as the central coordinator for services, hooks, and the application. It allows for adding/removing services, registering hooks, and accessing the application instance. Framework state can be checked to ensure safe access to game systems.

```cpp
#include "cIGZFrameWork.h"
#include "cRZCOMDllDirector.h"

// Access the framework from anywhere
cIGZFrameWork* pFramework = RZGetFrameWork();

// Framework state enumeration
enum FrameworkState {
    kStatePreFrameWorkInit = 1,
    kStatePreAppInit = 3,
    kStatePostAppInit = 6,
    kStatePreAppShutdown = 10,
    kStatePostAppShutdown = 11,
    kStatePostSystemServiceShutdown = 12
};

// Example: Access game application
cIGZApp* pApp = pFramework->Application();

// Example: Get a system service by ID
static const uint32_t kServiceID = 0x12345678;
static const uint32_t kInterfaceID = 0x87654321;
void* pService = nullptr;
if (pFramework->GetSystemService(kServiceID, kInterfaceID, &pService)) {
    // Use the service
}

// Example: Register and unregister hooks
pFramework->AddHook(myHookImplementation);
pFramework->RemoveHook(myHookImplementation);

// Example: Check current framework state
if (pFramework->GetState() >= cIGZFrameWork::kStatePostAppInit) {
    // Safe to access game systems
}
```

--------------------------------

### cIGZMessageServer2: Publish/Subscribe Message System (C++)

Source: https://context7.com/nsgomez/gzcom-dll/llms.txt

Illustrates how to use cIGZMessageServer2 for inter-object communication via a publish/subscribe pattern. This includes subscribing to message types, implementing the DoMessage handler, and managing subscriptions during application initialization and shutdown.

```cpp
#include "cIGZMessageServer2.h"
#include "cIGZMessageTarget2.h"
#include "cIGZMessage2Standard.h"
#include "GZServPtrs.h"

// Common message IDs
static const uint32_t kGZMSG_CityInited = 0x26d31ec1;
static const uint32_t kGZMSG_MonthPassed = 0x66956816;
static const uint32_t kGZMSG_OccupantInserted = 0x99ef1142;
static const uint32_t kGZMSG_OccupantRemoved = 0x99ef1143;

class cMyMessageHandler : public cRZCOMDllDirector, public cIGZMessageTarget2 {
public:
    // Implement DoMessage to handle incoming messages
    bool DoMessage(cIGZMessage2* pMessage) override {
        cIGZMessage2Standard* pStdMsg = static_cast<cIGZMessage2Standard*>(pMessage);
        uint32_t msgType = pMessage->GetType();

        switch (msgType) {
            case kGZMSG_CityInited:
                OnCityInitialized();
                break;

            case kGZMSG_MonthPassed:
                OnMonthPassed();
                break;

            case kGZMSG_OccupantInserted: {
                cISC4Occupant* pOccupant = (cISC4Occupant*)pStdMsg->GetVoid1();
                OnOccupantInserted(pOccupant);
                break;
            }
        }
        return true;
    }

    bool PostAppInit() override {
        // Subscribe to messages
        cIGZMessageServer2Ptr pMsgServer;
        if (pMsgServer) {
            pMsgServer->AddNotification(this, kGZMSG_CityInited);
            pMsgServer->AddNotification(this, kGZMSG_MonthPassed);
            pMsgServer->AddNotification(this, kGZMSG_OccupantInserted);
        }
        return true;
    }

    bool PreAppShutdown() override {
        // Unsubscribe from messages
        cIGZMessageServer2Ptr pMsgServer;
        if (pMsgServer) {
            pMsgServer->RemoveNotification(this, kGZMSG_CityInited);
            pMsgServer->RemoveNotification(this, kGZMSG_MonthPassed);
            pMsgServer->RemoveNotification(this, kGZMSG_OccupantInserted);
        }
        return true;
    }
};

```

--------------------------------

### cRZSysServPtr - Service Pointer Template

Source: https://context7.com/nsgomez/gzcom-dll/llms.txt

Smart pointer template for automatically retrieving and managing references to system services. Handles querying the framework and releasing references on destruction.

```APIDOC
## cRZSysServPtr - Service Pointer Template

### Description
Smart pointer template for automatically retrieving and managing references to system services. Handles querying the framework and releasing references on destruction.

### Method
N/A (Template usage)

### Endpoint
N/A

### Parameters
N/A

### Request Example
```cpp
#include "GZServPtrs.h"

// Pre-defined service pointer types
typedef cRZSysServPtr<cIGZMessageServer2, 1696765127ul, 83526747ul> cIGZMessageServer2Ptr;
typedef cRZSysServPtr<cISC4App, 651035072ul, 102ul> cISC4AppPtr;
typedef cRZSysServPtr<cIGZFileSystem, 3760207456ul, 544416093ul> cIGZFileSystemPtr;

// Example: Access message server
void SendMessage() {
    cIGZMessageServer2Ptr pMsgServer;
    if (pMsgServer) {
        // pMsgServer automatically retrieved from framework
        // Use -> operator to access interface methods
        pMsgServer->MessageSend(pMessage);
    }
    // Reference automatically released when pMsgServer goes out of scope
}

// Example: Access SC4 app
void GetCity() {
    cISC4AppPtr pApp;
    if (pApp) {
        cISC4City* pCity = pApp->GetCity();
        if (pCity) {
            // Work with city data
        }
    }
}
```

### Response
N/A (Template usage)
```

--------------------------------

### cIGZFrameWork - Game Framework Interface

Source: https://context7.com/nsgomez/gzcom-dll/llms.txt

The central coordinator for services, hooks, and the application. Use this to add/remove services, register hooks, and access the application instance.

```APIDOC
## cIGZFrameWork - Game Framework Interface

### Description
The central coordinator for services, hooks, and the application. Use this to add/remove services, register hooks, and access the application instance.

### Method
N/A (Global access via RZGetFrameWork())

### Endpoint
N/A

### Parameters
N/A

### Request Example
```cpp
#include "cIGZFrameWork.h"
#include "cRZCOMDllDirector.h"

// Access the framework from anywhere
cIGZFrameWork* pFramework = RZGetFrameWork();

// Framework state enumeration
enum FrameworkState {
    kStatePreFrameWorkInit = 1,
    kStatePreAppInit = 3,
    kStatePostAppInit = 6,
    kStatePreAppShutdown = 10,
    kStatePostAppShutdown = 11,
    kStatePostSystemServiceShutdown = 12
};

// Example: Access game application
cIGZApp* pApp = pFramework->Application();

// Example: Get a system service by ID
static const uint32_t kServiceID = 0x12345678;
static const uint32_t kInterfaceID = 0x87654321;
void* pService = nullptr;
if (pFramework->GetSystemService(kServiceID, kInterfaceID, &pService)) {
    // Use the service
}

// Example: Register and unregister hooks
pFramework->AddHook(myHookImplementation);
pFramework->RemoveHook(myHookImplementation);

// Example: Check current framework state
if (pFramework->GetState() >= cIGZFrameWork::kStatePostAppInit) {
    // Safe to access game systems
}
```

### Response
N/A (Direct C++ API usage)
```

--------------------------------

### Utilize cRZSysServPtr Smart Pointers for Service Access (C++)

Source: https://context7.com/nsgomez/gzcom-dll/llms.txt

The cRZSysServPtr is a smart pointer template for automatically retrieving and managing references to system services. It handles querying the framework and releasing references on destruction. Pre-defined types are available for common services like the message server and application.

```cpp
#include "GZServPtrs.h"

// Pre-defined service pointer types
typedef cRZSysServPtr<cIGZMessageServer2, 1696765127ul, 83526747ul> cIGZMessageServer2Ptr;
typedef cRZSysServPtr<cISC4App, 651035072ul, 102ul> cISC4AppPtr;
typedef cRZSysServPtr<cIGZFileSystem, 3760207456ul, 544416093ul> cIGZFileSystemPtr;

// Example: Access message server
void SendMessage() {
    cIGZMessageServer2Ptr pMsgServer;
    if (pMsgServer) {
        // pMsgServer automatically retrieved from framework
        // Use -> operator to access interface methods
        pMsgServer->MessageSend(pMessage);
    }
    // Reference automatically released when pMsgServer goes out of scope
}

// Example: Access SC4 app
void GetCity() {
    cISC4AppPtr pApp;
    if (pApp) {
        cISC4City* pCity = pApp->GetCity();
        if (pCity) {
            // Work with city data
        }
    }
}

```

--------------------------------

### cISC4App: SimCity 4 Application Interface (C++)

Source: https://context7.com/nsgomez/gzcom-dll/llms.txt

Shows how to access the main SimCity 4 application interface (cISC4App) to interact with game state, managers, and request game actions. This includes retrieving city and region information, enabling debug features, and managing game directories.

```cpp
#include "cISC4App.h"
#include "cISC4City.h"

static const uint32_t GZIID_cISC4App = 0x26CE01C0;

// Get SC4App from framework
cIGZFrameWork* pFramework = RZGetFrameWork();
cIGZApp* pApp = pFramework->Application();
cISC4App* pISC4App = nullptr;

if (pApp->QueryInterface(GZIID_cISC4App, (void**)&pISC4App)) {
    // Enable debug/cheat functionality
    pISC4App->SetDebugFunctionalityEnabled(true);

    // Get current city
    cISC4City* pCity = pISC4App->GetCity();
    if (pCity) {
        // Access city systems
        cISC4OccupantManager* pOccMgr = pCity->GetOccupantManager();
        cISC4LotManager* pLotMgr = pCity->GetLotManager();
        cISC4AdvisorSystem* pAdvisor = pCity->GetAdvisorSystem();
    }

    // Get current region
    cISC4Region* pRegion = pISC4App->GetRegion();
    cISC4RegionalCity* pRegionalCity = pISC4App->GetRegionalCity();

    // Get population
    int32_t population = pRegionalCity->GetPopulation();

    // Get cheat code manager
    cIGZCheatCodeManager* pCheatMgr = pISC4App->GetCheatCodeManager();

    // Get game directories
    cRZBaseString appDir, pluginDir, userDir;
    pISC4App->GetAppDirectory(appDir);
    pISC4App->GetPluginDirectory(pluginDir);
    pISC4App->GetUserDataDirectory(userDir);

    // Request game actions
    pISC4App->RequestSaveCity(true, false);  // Show notification, not fast save
    pISC4App->RequestGoToRegionView(true);   // Show confirmation dialog

    pISC4App->Release();
}

```

--------------------------------

### cIGZSystemService - System Service Interface

Source: https://context7.com/nsgomez/gzcom-dll/llms.txt

Interface for services that provide functionality and receive tick/idle callbacks. Services must be registered with the framework and can be retrieved by other directors.

```APIDOC
## cIGZSystemService - System Service Interface

### Description
Interface for services that provide functionality and receive tick/idle callbacks. Services must be registered with the framework and can be retrieved by other directors.

### Method
N/A (Class implementation)

### Endpoint
N/A

### Parameters
N/A

### Request Example
```cpp
#include "cIGZSystemService.h"
#include "cRZBaseSystemService.h"

static const uint32_t kMyServiceID = 0xABCDEF01;
static const int32_t kMyServicePriority = 1000;

class cMyService : public cRZBaseSystemService {
public:
    cMyService() : cRZBaseSystemService(kMyServiceID, kMyServicePriority) {}

    // Called for service initialization
    bool Init() override {
        return true;
    }

    // Called before service shutdown
    bool Shutdown() override {
        return true;
    }

    // Called on each game tick when registered with AddToTick
    bool OnTick(uint32_t dwTimeElapsed) override {
        // Perform periodic work
        return true;
    }

    // Called during idle time when registered with AddToOnIdle
    bool OnIdle(uint32_t dwUnknown) override {
        // Perform background work
        return true;
    }
};

// Register the service with the framework
cIGZFrameWork* pFramework = RZGetFrameWork();
cMyService* pService = new cMyService();

// Add to framework's service registry
pFramework->AddSystemService(pService);

// Enable tick callbacks
pFramework->AddToTick(pService);

// Enable idle callbacks
pFramework->AddToOnIdle(pService);

// Later: Remove from tick/idle and unregister
pFramework->RemoveFromTick(pService);
pFramework->RemoveFromOnIdle(pService);
pFramework->RemoveSystemService(pService);
```

### Response
N/A (Class implementation)
```

--------------------------------

### cRZAutoRefCount: Smart Pointer for GZCOM Objects (C++)

Source: https://context7.com/nsgomez/gzcom-dll/llms.txt

Demonstrates the usage of cRZAutoRefCount, a smart pointer template for automatic reference count management of GZCOM objects. It ensures proper AddRef/Release calls to prevent memory leaks and supports copy and move semantics.

```cpp
#include "cRZAutoRefCount.h"

// Basic usage - takes ownership without adding reference
cRZAutoRefCount<cISC4Occupant> pOccupant;
pCity->GetOccupantManager()->GetOccupant(id, pOccupant.AsPPVoid());

// Add reference on construction
cRZAutoRefCount<cISC4Lot> pLot(existingLot, cRZAutoRefCount<cISC4Lot>::kAddRef);

// Use like a regular pointer
if (pOccupant) {
    uint32_t type = pOccupant->GetType();
    pOccupant->DoSomething();
}

// Copy semantics - automatically manages reference counts
cRZAutoRefCount<cISC4City> pCity1 = pApp->GetCity();
cRZAutoRefCount<cISC4City> pCity2 = pCity1;  // AddRef called

// Move semantics
cRZAutoRefCount<cISC4City> pCity3 = std::move(pCity1);  // No AddRef

// Manual reset
pOccupant.Reset();  // Calls Release

// Get raw pointer address for QueryInterface output
void** ppvObj = pOccupant.AsPPVoid();
cISC4Occupant** ppOccupant = pOccupant.AsPPObj();
```

--------------------------------

### Register Class Object Factories with cRZCOMDllDirector

Source: https://context7.com/nsgomez/gzcom-dll/llms.txt

This C++ code illustrates how to register factory methods for custom classes using cRZCOMDllDirector. It defines a unique class ID, a custom class inheriting from cIGZUnknown, and factory functions. These factories allow the game to create instances of your custom classes. Dependencies include 'cRZCOMDllDirector.h'.

```cpp
#include "cRZCOMDllDirector.h"

// Define a unique class ID for your custom class
static const uint32_t kCLSID_MyCustomClass = 0x11223344;

class cMyCustomClass : public cIGZUnknown {
public:
    // Your implementation
    bool QueryInterface(uint32_t riid, void** ppvObj) override;
    uint32_t AddRef() override;
    uint32_t Release() override;

    void DoSomething();

private:
    uint32_t refCount = 0;
};

// Factory function type 1: Returns cIGZUnknown*
cIGZUnknown* CreateMyCustomClass() {
    return new cMyCustomClass();
}

// Factory function type 2: Takes interface ID and output pointer
bool CreateMyCustomClass2(uint32_t iid, void** ppvObj) {
    cMyCustomClass* pObj = new cMyCustomClass();
    if (pObj->QueryInterface(iid, ppvObj)) {
        return true;
    }
    delete pObj;
    return false;
}

class cMyDirector : public cRZCOMDllDirector {
public:
    cMyDirector() {
        // Register class factory using either method
        AddCls(kCLSID_MyCustomClass, CreateMyCustomClass);
        // Or: AddCls(kCLSID_MyCustomClass, CreateMyCustomClass2);
    }

    uint32_t GetDirectorID() const override {
        return 0xAABBCCDD;
    }
};

// Other code can now create instances via GZCOM
cIGZCOM* pCOM = RZGetCOMDllDirector()->GZCOM();
cMyCustomClass* pObj = nullptr;
if (pCOM->GetClassObject(kCLSID_MyCustomClass, kMyInterfaceID, (void**)&pObj)) {
    pObj->DoSomething();
    pObj->Release();
}

```

--------------------------------

### cISC4App - SimCity 4 Application Interface

Source: https://context7.com/nsgomez/gzcom-dll/llms.txt

The cISC4App interface provides the primary access point to the SimCity 4 game state, including preferences, cities, regions, and various game managers. It allows for interaction with core game functionalities and systems.

```APIDOC
## cISC4App - SimCity 4 Application Interface

### Description
The main application interface providing access to game state, preferences, cities, regions, and various game managers.

### Method
N/A (Interface)

### Endpoint
N/A (Interface)

### Parameters
N/A (Interface)

### Request Example
```cpp
#include "cISC4App.h"
#include "cISC4City.h"

static const uint32_t GZIID_cISC4App = 0x26CE01C0;

// Get SC4App from framework
cIGZFrameWork* pFramework = RZGetFrameWork();
cIGZApp* pApp = pFramework->Application();
cISC4App* pISC4App = nullptr;

if (pApp->QueryInterface(GZIID_cISC4App, (void**)&pISC4App)) {
    // Enable debug/cheat functionality
    pISC4App->SetDebugFunctionalityEnabled(true);

    // Get current city
    cISC4City* pCity = pISC4App->GetCity();
    if (pCity) {
        // Access city systems
        cISC4OccupantManager* pOccMgr = pCity->GetOccupantManager();
        cISC4LotManager* pLotMgr = pCity->GetLotManager();
        cISC4AdvisorSystem* pAdvisor = pCity->GetAdvisorSystem();
    }

    // Get current region
    cISC4Region* pRegion = pISC4App->GetRegion();
    cISC4RegionalCity* pRegionalCity = pISC4App->GetRegionalCity();

    // Get population
    int32_t population = pRegionalCity->GetPopulation();

    // Get cheat code manager
    cIGZCheatCodeManager* pCheatMgr = pISC4App->GetCheatCodeManager();

    // Get game directories
    cRZBaseString appDir, pluginDir, userDir;
    pISC4App->GetAppDirectory(appDir);
    pISC4App->GetPluginDirectory(pluginDir);
    pISC4App->GetUserDataDirectory(userDir);

    // Request game actions
    pISC4App->RequestSaveCity(true, false);  // Show notification, not fast save
    pISC4App->RequestGoToRegionView(true);   // Show confirmation dialog

    pISC4App->Release();
}
```

### Response
N/A (Interface)

### Response Example
N/A (Interface)
```

--------------------------------

### cIGZMessageServer2 - Message System

Source: https://context7.com/nsgomez/gzcom-dll/llms.txt

The cIGZMessageServer2 interface manages inter-object communication using a publish/subscribe pattern. Objects can subscribe to specific message types and implement the DoMessage method to receive and handle notifications.

```APIDOC
## cIGZMessageServer2 - Message System

### Description
The message server handles inter-object communication through a publish/subscribe pattern. Subscribe to message types and implement DoMessage to receive notifications.

### Method
N/A (Interface)

### Endpoint
N/A (Interface)

### Parameters
N/A (Interface)

### Request Example
```cpp
#include "cIGZMessageServer2.h"
#include "cIGZMessageTarget2.h"
#include "cIGZMessage2Standard.h"
#include "GZServPtrs.h"

// Common message IDs
static const uint32_t kGZMSG_CityInited = 0x26d31ec1;
static const uint32_t kGZMSG_MonthPassed = 0x66956816;
static const uint32_t kGZMSG_OccupantInserted = 0x99ef1142;
static const uint32_t kGZMSG_OccupantRemoved = 0x99ef1143;

class cMyMessageHandler : public cRZCOMDllDirector, public cIGZMessageTarget2 {
public:
    // Implement DoMessage to handle incoming messages
    bool DoMessage(cIGZMessage2* pMessage) override {
        cIGZMessage2Standard* pStdMsg = static_cast<cIGZMessage2Standard*>(pMessage);
        uint32_t msgType = pMessage->GetType();

        switch (msgType) {
            case kGZMSG_CityInited:
                OnCityInitialized();
                break;

            case kGZMSG_MonthPassed:
                OnMonthPassed();
                break;

            case kGZMSG_OccupantInserted: {
                cISC4Occupant* pOccupant = (cISC4Occupant*)pStdMsg->GetVoid1();
                OnOccupantInserted(pOccupant);
                break;
            }
        }
        return true;
    }

    bool PostAppInit() override {
        // Subscribe to messages
        cIGZMessageServer2Ptr pMsgServer;
        if (pMsgServer) {
            pMsgServer->AddNotification(this, kGZMSG_CityInited);
            pMsgServer->AddNotification(this, kGZMSG_MonthPassed);
            pMsgServer->AddNotification(this, kGZMSG_OccupantInserted);
        }
        return true;
    }

    bool PreAppShutdown() override {
        // Unsubscribe from messages
        cIGZMessageServer2Ptr pMsgServer;
        if (pMsgServer) {
            pMsgServer->RemoveNotification(this, kGZMSG_CityInited);
            pMsgServer->RemoveNotification(this, kGZMSG_MonthPassed);
            pMsgServer->RemoveNotification(this, kGZMSG_OccupantInserted);
        }
        return true;
    }
};
```

### Response
N/A (Interface)

### Response Example
N/A (Interface)
```

--------------------------------

### GZCOM DLL Export Function: GZDllGetGZCOMDirector (C++)

Source: https://context7.com/nsgomez/gzcom-dll/llms.txt

This C++ code defines the essential `GZDllGetGZCOMDirector` function, which must be exported by every GZCOM-compatible DLL. It returns a pointer to the plugin's COM director, enabling the game to interact with the plugin. Platform-specific export macros are used for Windows and macOS.

```cpp
// Platform-specific export macro
#if defined(_WIN32)
#define EXPORT __declspec(dllexport)
#elif defined(__APPLE__)
#define EXPORT __attribute__((visibility("default")))
#endif

// This function is automatically generated by cRZCOMDllDirector.cpp
// You just need to implement RZGetCOMDllDirector()
extern "C" EXPORT cIGZCOMDirector* GZDllGetGZCOMDirector(void) {
    return static_cast<cIGZCOMDirector*>(RZGetCOMDllDirector());
}

// Implement this function in your plugin to return your director
cRZCOMDllDirector* RZGetCOMDllDirector() {
    static cMyPluginDirector sDirector; // Replace with your actual director class
    return &sDirector;
}

// Convenience function to get GZCOM from anywhere
cIGZCOM* GZCOM(void) {
    return RZGetCOMDllDirector()->GZCOM();
}

```

--------------------------------

### cRZAutoRefCount - Automatic Reference Counting

Source: https://context7.com/nsgomez/gzcom-dll/llms.txt

The cRZAutoRefCount template provides smart pointer functionality for automatic reference count management of GZCOM objects. It ensures proper AddRef/Release calls, preventing memory leaks and simplifying object lifecycle management.

```APIDOC
## cRZAutoRefCount - Automatic Reference Counting

### Description
Smart pointer template for automatic reference count management of GZCOM objects. Ensures proper AddRef/Release calls and prevents memory leaks.

### Method
N/A (Class Template)

### Endpoint
N/A (Class Template)

### Parameters
N/A (Class Template)

### Request Example
```cpp
// Basic usage - takes ownership without adding reference
cRZAutoRefCount<cISC4Occupant> pOccupant;
pCity->GetOccupantManager()->GetOccupant(id, pOccupant.AsPPVoid());

// Add reference on construction
cRZAutoRefCount<cISC4Lot> pLot(existingLot, cRZAutoRefCount<cISC4Lot>::kAddRef);

// Use like a regular pointer
if (pOccupant) {
    uint32_t type = pOccupant->GetType();
    pOccupant->DoSomething();
}

// Copy semantics - automatically manages reference counts
cRZAutoRefCount<cISC4City> pCity1 = pApp->GetCity();
cRZAutoRefCount<cISC4City> pCity2 = pCity1;  // AddRef called

// Move semantics
cRZAutoRefCount<cISC4City> pCity3 = std::move(pCity1);  // No AddRef

// Manual reset
pOccupant.Reset();  // Calls Release

// Get raw pointer address for QueryInterface output
void** ppvObj = pOccupant.AsPPVoid();
cISC4Occupant** ppOccupant = pOccupant.AsPPObj();
```

### Response
N/A (Class Template)

### Response Example
N/A (Class Template)
```

--------------------------------

### Register Custom Cheat Codes with cIGZCheatCodeManager

Source: https://context7.com/nsgomez/gzcom-dll/llms.txt

This C++ snippet demonstrates how to register custom cheat codes with the cIGZCheatCodeManager. It involves defining cheat IDs, registering them with the manager, and subscribing to cheat issuance messages to handle custom cheat code execution. Dependencies include 'cIGZCheatCodeManager.h' and 'cRZBaseString.h'.

```cpp
#include "cIGZCheatCodeManager.h"
#include "cRZBaseString.h"

static const uint32_t kGZIID_cIGZCheatCodeManager = 0xa1085722;
static const uint32_t kGZMSG_CheatIssued = 0x230e27ac;

// Define your cheat IDs
static const uint32_t kCheatMyCustomCheat = 0xDEADBEEF;
static const char* kszCheatMyCustomCheat = "MyCheatCommand";

class cCheatHandler : public cRZMessage2COMDirector {
public:
    bool PostAppInit() override {
        cISC4AppPtr pApp;
        if (pApp) {
            cIGZCheatCodeManager* pCheatMgr = pApp->GetCheatCodeManager();
            if (pCheatMgr) {
                // Register for cheat notifications
                pCheatMgr->AddNotification2(this, 0);

                // Register your custom cheat code
                cRZBaseString cheatName(kszCheatMyCustomCheat);
                pCheatMgr->RegisterCheatCode(kCheatMyCustomCheat, cheatName);
            }
        }

        // Also subscribe to cheat messages
        cIGZMessageServer2Ptr pMsgServer;
        if (pMsgServer) {
            pMsgServer->AddNotification(this, kGZMSG_CheatIssued);
        }

        return true;
    }

    bool DoMessage(cIGZMessage2* pMessage) override {
        if (pMessage->GetType() == kGZMSG_CheatIssued) {
            cIGZMessage2Standard* pStdMsg = static_cast<cIGZMessage2Standard*>(pMessage);
            uint32_t cheatID = pStdMsg->GetData1();
            cIGZString* pCheatText = static_cast<cIGZString*>(pStdMsg->GetVoid2());

            if (cheatID == kCheatMyCustomCheat) {
                // Handle your cheat code
                ExecuteMyCheat(pCheatText);
                return true;
            }
        }
        return true;
    }
};

```

--------------------------------

### GZCOM cIGZUnknown Interface Definition (C++)

Source: https://github.com/nsgomez/gzcom-dll/wiki/Component-Object-Model

Defines the base cIGZUnknown interface for GZCOM objects, providing essential COM-like functionality for interface querying and reference counting. This is a core component for object interaction within the GZCOM framework.

```cpp
class cIGZUnknown
{
    public:
        virtual bool QueryInterface(uint32_t riid, void** ppvObj) = 0;
        virtual uint32_t AddRef(void) = 0;
        virtual uint32_t Release(void) = 0;
};

```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.