libultraship (LUS)

The event system allows mods to hook into engine and game loop lifecycle points without modifying source code.

1. Definition: Use DEFINE_EVENT to create a struct type and a global EventID.
2. Registration: Every event must be registered once at engine startup using REGISTER_EVENT before it can be used.
3. Dispatching: Use CALL_EVENT to fire an event. If the event is cancellable, use CALL_CANCELLABLE_EVENT.
4. Listening: Use REGISTER_LISTENER to attach a callback function to an event.

Important: Always store the ListenerID returned by REGISTER_LISTENER and call UNREGISTER_LISTENER in your MOD_EXIT function to prevent use-after-free errors when the mod is unloaded.

// Define an event
DEFINE_EVENT(MyDataEvent, int someValue; float otherValue;);

// Register it at startup
REGISTER_EVENT(MyDataEvent);

// Dispatch it
CALL_EVENT(MyDataEvent, .someValue = 42, .otherValue = 3.14f);

Epoch 2 initialization is centered around ship/core components. You must choose one of two setup styles based on your port's requirements:

1. CreateDefaultInstance(...) (Helper-driven)

Use this for the fastest path to a running baseline. LUS handles the standard component graph and ordering internally.

• Best for: Simple ports or quick baselines.
• Trade-offs: Less control over concrete component construction and subsystem composition.

2. CreateInstance(...) + manual component graph (Recommended)

Use this when you need explicit control over startup, dependencies, and injection.

• Best for: Most ports, especially those with custom window, input, resource, or event behavior.
• Pros: Full ownership of component add-order, easier to inject custom implementations, and better long-term maintainability.
• Cons: Requires more boilerplate and manual enforcement of dependency sequencing.

An .o2r file is a ZIP archive. The engine specifically looks for manifest.json and build.gen at the root. The internal structure typically looks like this:

my-mod.o2r
├── manifest.json          # Required: mod metadata
├── build.gen              # Optional: list of C source files to JIT-compile
├── dist/
│   └── mod.c              # Amalgamated C source (referenced by build.gen)
├── binaries/
│   ├── linux_x64.so       # Optional pre-compiled binaries
│   ├── windows_x64.dll
│   └── darwin.dylib
└── <game assets ...>      # Other resource files

my-mod.o2r
├── manifest.json          # Required: mod metadata
├── build.gen              # Optional: list of C source files to JIT-compile
├── dist/
│   └── mod.c              # Amalgamated C source (referenced by build.gen)
├── binaries/
│   ├── linux_x64.so       # Optional pre-compiled binaries per platform
│   ├── windows_x64.dll
│   └── darwin.dylib
└── <game assets ...>      # Any other resource files the mod needs

libultraship (LUS) uses epoch semantic versioning to manage large-scale architectural refactors. This system uses a four-part version number: epoch.major.minor.patch (e.g., 1.2.3.4 or 2.0.0.0).

How to interpret version numbers

• New Epoch (X.y.z.w): When the first digit (the epoch) increments, it signals a major architectural overhaul (e.g., redesigning the context/component model). The main branch moves to this new epoch, meaning it may not be production-ready and commits may change during the refactor.
• Stable Epoch: The previous epoch remains a maintained branch. It receives critical fixes and allows for small breaking changes (which increment the major digit within that epoch, e.g., 1.23.0.1). This provides a stable baseline for ports that are not yet ready to migrate to the new architecture.

When a new epoch is triggered

• Changes to core architectural patterns (e.g., context/component model redesign).
• Coordinated breaking changes across multiple subsystems.
• Refactors expected to span several months of incremental work.