babylon.engine.scenarios.base

Scenario ABC + auto-registry — ADR-006.1 / Spec 059 US4.

Lifts the implicit “scenario builder” contract that 6 free functions duplicate into an abstract base class with auto-registry via __init_subclass__. Existing free-function names are preserved as thin shims in this package’s __init__.py.

Usage:

class MyScenario(Scenario):
    name = "my_scenario"
    description = "Brief description"

    def build(self) -> tuple[WorldState, SimulationConfig, GameDefines]:
        # ... assemble territories, classes, relationships, return tuple
        ...

The subclass auto-registers via __init_subclass__; no manual registry edit is required. Lookup via _SCENARIO_REGISTRY[name].

For the 6 historical builders, subclasses delegate build() to the free-function implementations in _legacy.py / _legacy_wayne.py to preserve byte-equality with the pre-Bundle-2 baseline (SC-007).

Functions

get_scenario(name)	Look up a Scenario subclass by name.
list_scenarios()	Return the names of all registered scenarios, sorted.

Classes

Scenario()

Abstract base for scenario builders.

class babylon.engine.scenarios.base.Scenario

Bases: ABC

Abstract base for scenario builders.

Subclasses MUST set name (ClassVar str) and description (ClassVar str), and implement build(). They auto-register via __init_subclass__().

Optional build_territories / build_classes / build_relationships methods are provided for the new-style composition pattern; subclasses MAY use them with a custom build() that calls them, or override build() directly (the pattern used by Bundle 2’s port of the 6 legacy builders).

name: ClassVar[str]

description: ClassVar[str] = ''

abstractmethod build(*args, **kwargs)

Build the scenario and return (state, config, defines).

Return type:

tuple[WorldState, SimulationConfig, GameDefines]

Parameters:

• args (Any)

• kwargs (Any)

build_territories()

Optional: territory builder for composition pattern.

Return type:

dict[str, Any]

build_classes()

Optional: social-class builder for composition pattern.

Return type:

dict[str, Any]

build_relationships()

Optional: relationship builder for composition pattern.

Return type:

dict[str, Any]

classmethod __init_subclass__(**kwargs)

Auto-register subclass in _SCENARIO_REGISTRY keyed on cls.name.

Raises:

ValueError – When two subclasses share the same name (collision detection at import time, per US4 acceptance #2).

Return type:

None

Parameters:

kwargs (Any)

babylon.engine.scenarios.base.get_scenario(name)

Look up a Scenario subclass by name.

Return type:

type[Scenario]

Parameters:

name (str)

babylon.engine.scenarios.base.list_scenarios()

Return the names of all registered scenarios, sorted.

Return type:

list[str]