Controller Families - cressie176/Load64 GitHub Wiki

1. Overview

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

A controller family defines a reusable template for a brand or series of controllers that share common characteristics. It captures the human-readable names for each control (e.g. "A", "Left Trigger"), their canonical LoadC64 names, and the OS event identifiers used to detect input.

Controller family mappings serve as a seed template for devices in that family. Event identifiers are per-device and may vary even within a family due to driver variations, firmware versions, or mode switches (e.g. XInput vs DirectInput). Controller configurations are the source of truth for event identifiers. When a device's actual event identifiers differ from the family template, create a controller configuration that overrides the specific events.

At most one controller family may be marked as the default. When a family is the default, its configuration is automatically applied to all controllers.

A controller family may also define environment variables to be set when launching VICE.

2. Tables

ControllerFamily

Field	Type	PK	Unique	Description
id	integer	yes		Surrogate primary key.
name	text		yes	Display name for the family (e.g. `"Logitech"`).
default	boolean		yes	Whether this is the default family. At most one row may be `true`.

3. Example

controller_family

id	name	default
1	Logitech	false