Sidecar Developer SDK Guide

The Sidecar architecture allows developers to create custom gameplay services (Chat, Banking, Quests, Guilds, Hub Progression) as independent processes that connect to the core engine over loopback TCP (127.0.0.1:55557).

Core Architecture

[Unity Client] ▲ (Internet: TCP Wire Envelope - Opcode 0x0D) │ [CVL CORE Server Engine] (Authoritative Spatial Host) ▲ │ (Loopback TCP: 127.0.0.1:55557) ▼ [Sidecar Microservice Daemons] (Chat, Banking, Quests, Hub Progression)

Creating a Custom Sidecar

To build a new microservice, import BaseSidecarService and register action handlers using sub-opcodes:

from sdk.sidecar_sdk import BaseSidecarService, STATUS_OK

class QuestService(BaseSidecarService):
    def __init__(self):
        super().__init__(
            service_id=0x04,
            service_name="QuestService",
            auth_token="cvl_secret_sidecar_auth_key_v1"
        )

    @BaseSidecarService.on_action(sub_opcode=0x01)
    def handle_quest_query(self, auth_net_id, auth_eid, req_id, payload):
        # Handle custom quest state resolution
        self.send_reply(auth_eid, sub_opcode=0x01, req_id=req_id, status_code=STATUS_OK, payload=b"QUEST_DATA")

if __name__ == "__main__":
    service = QuestService()
    service.run()

Resilience Guarantees
Crash Isolation: If a custom sidecar crashes, the spatial kernel does not drop players or stutter its 30Hz tick loop.

Fast-Fail Bouncing: If a client requests an offline service slot, the broker returns an instant STATUS_ERR_SERVICE_OFFLINE (0x07) response in under 2ms.

Mid-Transaction Disconnect Safety: Responses are addressed to persistent player entity IDs (auth_eid), preventing stale responses from misrouting if a connection drops and its 16-bit Network ID is recycled.