Controllers - cressie176/Load64 GitHub Wiki

1. Overview

┌───────────────────────────────┐           ┌───────────────────────────────────────────────┐
│                               │          ╱│                                               │
│       ControllerFamily        │─────────○─│                  Controller                   │
│                               │          ╲│                                               │
└───────────────────────────────┘           ├───────────────────────────────────────────────┤
                                            │ id: integer [pk]                              │
                                            │ controller_family: integer [fk]               │
                                            │ hardware_guid: text [required, unique]        │
                                            │ name: text [required, unique]                 │
                                            └───────────────────────────────────────────────┘
                                                      │                         │
                                                      │                         │
                                                      │                         │
                                                      ○                         ○
                                                     ╱│╲                       ╱│╲
                                            ┌───────────────────┐   ┌───────────────────────┐
                                            │                   │   │                       │
                                            │ ControllerControl │   │  EnvironmentVariable  │
                                            │                   │   │                       │
                                            └───────────────────┘   └───────────────────────┘

A controller defines how a specific physical device maps raw OS input events to LoadC64's canonical controls. It is identified by its hardware GUID and may optionally belong to a controller family, inheriting that family's control mappings as a base. Any controls or environment variables defined on the controller override the family values.

2. Tables

Controller

Field	Type	PK	FK	Nullable	Unique	Description
id	integer	yes				Surrogate primary key.
controller_family_id	integer		ControllerFamily.id	yes		The family this controller belongs to.
hardware_guid	text				yes	OS-level hardware GUID identifying the physical device.
name	text				yes	Display name for the controller (e.g. `"Logitech Dual Action"`).

3. GUID and Identical Controllers

The hardware_guid is derived from the device's vendor and product IDs. Two physical controllers of the same model will share the same GUID. LoadC64 has no reliable way to distinguish between them across sessions — the OS device index changes each time controllers are connected or the application restarts.

As a result, per-controller overrides are only meaningful when a given GUID uniquely identifies a single physical device. If two identical controllers are in use, their overrides are indistinguishable and LoadC64 cannot guarantee which physical device receives which configuration. In practice, users with multiple identical controllers should configure the shared behaviour at the family level rather than the controller level.

4. Override Merge Behaviour

When a controller belongs to a family, its ControllerControl rows are merged with the family's by name:

Specified fields on the controller override the family values
Unspecified fields inherit from the family
Controls defined only in the family remain unchanged
Controls defined only in the controller are added

The same merge behaviour applies to environment variables.

5. Example

controller

id	controller_family_id	hardware_guid	name
1	1	030000005e040000eafd..	Logitech Dual Action
2	null	050000004c050000cc09..	DualSense Edge