Enums¶
Enums replace raw numeric literals—such as color indices, hardware flags, or game states—with readable symbolic constants across immediate operands (lda #VicIIColors.BLACK), .byte values, and .word tables.
Enum Scopes and Precedence¶
Regenerator 2000 resolves enum definitions across three scopes in priority order, letting you override built-in hardware definitions without modifying global files:
flowchart TB
Project["`Project-Specific Enums
• Stored in .regen2000proj
• Supports Undo / Redo
• Highest precedence`"]
Global["`Global Custom Enums
• Shared across projects
• Stored as TOML in config dir
• Overrides system enums`"]
System["`Built-in System Enums
• Curated per machine (e.g. VicIIColors)
• Read-only, embedded in binary
• Lowest precedence`"]
Project -->|Overrides| Global
Global -->|Overrides| System
| Level | Scope | Storage | Precedence | Undo / Redo |
|---|---|---|---|---|
| 1. Project-Specific | Active project only | Inside .regen2000proj |
Highest | Yes (U / Ctrl+R) |
| 2. Global Custom | All projects on your machine | enum-*.toml in config dir |
Medium | — |
| 3. Built-in System | Curated per target system | Embedded (read-only) | Lowest | — |
Portability & Sharing¶
- System & Global Enums: Project files store only the enum name reference—not a full copy of the definition.
- Project-Local Enums: Serialized directly inside
.regen2000projso shared projects stay self-contained. If a collaborator's.regen2000projreferences a missing global enum, clone it into the local project pool via Manage Enums.
Using Enums in the TUI¶
Applying an Enum¶
- Move the cursor to an immediate operand (
lda #$00),.byte, or.wordvalue and press E (or Edit → Apply Enum...). - Matching enums that define the current value float to the top in bold with the variant preview (e.g.,
VicIIColors (BLACK)). - Filter by typing in the search box, switch selection with Up / Down (pick
<None> (Clear Enum Usage)to clear, or press Ctrl+N to create a new enum inline), and press Enter to apply.
Managing Enums¶
Open Edit → Manage Enums... (F10 or Alt+T) and switch across the Project, Global, and System tabs to Add, Edit, Delete (unused enums only), or Clone enums between project and global pools.
Custom Global Enums¶
Create enum-*.toml files in your configuration directory to share custom constants across projects or override built-in system enums:
| Platform | Configuration Directory |
|---|---|
| macOS | ~/Library/Application Support/regenerator2000/ |
| Linux | ~/.config/regenerator2000/ |
| Windows | C:\Users\<User>\AppData\Roaming\regenerator2000\config\ |
Verify Your Path
Run regenerator2000 --help—the exact configuration directory path for your system prints near the bottom of the output.
Creating from Built-in Templates¶
-
Dump the built-in enum files as starting templates:
-
Edit an existing file or add a new
enum-<Name>.tomlfile:enum-CustomColors.tomlname = "CustomColors" # (1)! description = "My custom system color definitions" [variants] # (2)! BLACK = 0 WHITE = 1 RED = 2- Reuse a built-in enum name (like
"VicIIColors") to override it globally across all projects. - Map each constant name to its integer value (supports decimal, or hex/binary if quoted/formatted as TOML integers).
- Reuse a built-in enum name (like
-
Restart Regenerator 2000—the enum appears automatically under the Global tab in Manage Enums and Apply Enum.
Assembler Syntax Support¶
On export, Regenerator 2000 lowers enum definitions and usages to each assembler's native namespace or scoping syntax:
Groups variants inside .block / .bend and accesses members with .:
Groups variants inside .enum / .endenum and accesses members with :::
Groups variants inside .namespace with .label entries and accesses members with .: