Curved Spacetime Engine Specification

Version
0.1.0-build.108
Status
Normative, and violated: describes how the engine should work. Where the code disagrees, the code is wrong.
Licence
GPL-3.0-or-later

1. Introduction

Curved Spacetime is assembled at runtime from independently built modules. A loader discovers those modules and hands their entrypoints to the engine, and the engine drives them through a fixed initialization protocol, then runs the callbacks they register until it is stopped. This document is for the authors of engines. It specifies what a conforming engine must do: how it drives initialization through a loader, and when it calls each callback, on which thread, and what a failure does.

It is complete on its own. Everything an engine compiles against is reproduced in Appendix A, and every requirement that binds an engine is stated here, so a third party can implement one without reading any other document. MainModuleEngineImpl is the reference engine.

What a callback computes is deliberately out of scope.

1.1 Versioning of this document

This specification is published per version of Curved Spacetime, at specs/<version>/, alongside the API documentation. The cadence tracks the project's own SemVer 2.0.0 maturity:

Project stage A new specification version is cut
Before 0.1.0 (current) per build
0.x.y per minor version
1.0.0 and later per major version

The project is currently in the pre-0.1.0 stage, so each release build publishes its own copy of this document. 0.1.0 will be released once the project is functional, even if incomplete; from that point the cadence drops to per minor version.

2. Conformance

The key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL in this document are to be interpreted as described in RFC 2119.

Requirements are numbered Rn and are individually linkable. The numbers are stable identifiers shared across the project's specifications: a number missing here belongs to a requirement that binds no engine, and a requirement that binds more than one kind of implementation carries the same number and wording wherever it appears.

A conforming engine is a subclass of io.codetoil.curved_spacetime.api.Engine that satisfies every requirement in §4 and §5.

3. Terminology

engine
A subclass of the abstract class Engine. It passes itself to the loader's prepareModInit, invokes every module's main entrypoint, and, once initialization is complete, runs the modules' callbacks.
loader
An implementation of CurvedSpacetimeLoader. It maps an entrypoint name and type to a list of entrypoint instances.
module
A unit of functionality with its own JPMS module, Gradle subproject, configuration file, and at least one entrypoint.
main entrypoint
A module's implementation of ModuleInitializer, registered under the entrypoint name main.
dependent entrypoint
A class registered by module B under module A's dependent entrypoint name, by which B learns of A's main entrypoint.
callback
A MainCallback, or a SceneCallback bound to one scene: module code the engine runs once initialization is complete.

4. Initialization

R6. prepareModInit MUST be called by the engine exactly once, before any entrypoint is invoked, with the run directory and the engine instance. A loader MUST retain the engine reference such that getEngine() returns it thereafter.

R10. invokeEntrypoints MUST apply the consumer to every entrypoint getEntrypoints would return for the same arguments. It MUST NOT impose an ordering, and callers MUST NOT depend on one.

R20. The engine MUST, in order: load its own configuration; call prepareModInit; then invoke every main entrypoint's onInitialize. The engine's own configuration MUST be stored at config/<engine key>.config, relative to the run directory, in java.util.Properties text format, where the engine key is the name of the engine's project directory (for this engine, curved-spacetime-main-module). The property keys are the engine's to choose.

R21. The engine MUST invoke main entrypoints concurrently, and MUST NOT assume any completion order.

R22. If any entrypoint terminates abnormally, the engine MUST propagate that failure rather than continuing with a partially initialized module set.

R28. The executor the engine uses to invoke entrypoints MUST be effectively unbounded — it MUST be able to run every entrypoint of a given name concurrently. Both TransferQueue.transfer and TransferQueue.take block until the other side arrives, so a producer and its consumer MUST be runnable at the same time. A bounded pool deadlocks as soon as its threads are occupied by consumers whose producers are still queued.

In the reference engine this requirement is satisfied by Executors.newCachedThreadPool(), and the documentation of Engine.callDependents in Appendix A records why the pool must stay unbounded. It is stated here as a requirement because substituting a fixed pool is an easy and catastrophic change.

R29. An implementation SHOULD bound the handshake in time and fail with a diagnostic naming the unsatisfied dependency, rather than blocking indefinitely. A missing or miscounted dependency otherwise manifests as a silent hang at startup with no indication of which module is waiting.

5. Callbacks

Once initialization is complete, the engine runs module code through callbacks. A module registers a MainCallback for work independent of any scene, or a generator from which the engine makes one SceneCallback per scene. The engine calls each callback's init once, then its loop repeatedly, at the rate its getFPS() reports, and its clean when the engine stops. What a callback computes is out of scope (§1); this section fixes when it is called, on which thread, and what a failure does.

5.1 Lifecycle

R42. The engine MUST call every callback's init, loop, and clean from a single thread, the callback thread. A callback MAY therefore hold mutable state without synchronising it against other callbacks.

R43. The engine MUST call a callback's init exactly once, and before the first call to its loop.

R44. The engine MUST apply a registered generator exactly once to every scene: each scene that exists when the generator is registered, and each scene registered afterwards. Every callback so produced is subject to R42 and R43.

R45. registerMainCallback and registerSceneCallbackGenerator MUST return a future that completes once the init calls the registration causes have finished: normally if every one returned, exceptionally if one threw.

5.2 Failure and shutdown

R46. If a callback's init or loop, or a generator applied under R44, throws, the engine MUST log the throwable, with its stack trace, at SEVERE, before it releases anything. It MUST then stop as by clean (R47). It MUST NOT discard the throwable, and MUST NOT go on calling the remaining callbacks as though nothing had failed.

Logging comes first so that the failure is on record even if the teardown it triggers fails as well. A throwable that is caught and dropped, captured in a Future nobody reads, or thrown out of a periodic task — whose executor then suppresses every later run without a word — presents as a hang rather than an error.

R47. The engine's clean MUST stop the callback loop without interrupting the callback thread; MUST call clean on every registered callback, including one whose init threw, and deregister it, so that no callback is cleaned twice; and MUST then shut down the callback executor. It MUST clean every scene callback before any main callback, and main callbacks in the reverse of the order in which their init was called. A second call MUST be a no-op. Called from a callback's loop, it ends the current tick: the engine MUST NOT call loop on any callback once clean has been called, and MUST NOT report the call as a failure under R46. Only the callback thread calls it.

The order is reverse dependency order. A scene callback is built from what main callbacks provide — a renderer's swap chain and surface come from the Vulkan module's device and instance — and native APIs require an object's children to be destroyed before the object itself.

R48. Once clean has been called, the engine MUST ignore every registration whose init has not started, including one made before the call: it MUST NOT call the callback's init, and the registration's future MUST complete normally, immediately for a registration made after the call. It SHOULD log that the registration was ignored.

6. Conformance checklist

6.1 Initialization

6.2 Callbacks

Appendix A. API source

These files make up io.codetoil.curved_spacetime.api, the JPMS module, built from curved-spacetime-api-module, that every module, loader and engine compiles against. Each is reproduced in full. The declarations are normative. The documentation comments are informative: where one disagrees with a numbered requirement, the requirement governs. This code can also be found in the git repository.

A.1 module-info.java

/**
 * Curved Spacetime is a work-in-progress easy-to-use modular simulator for General Relativity.<br>
 * Copyright (C) 2023-2026 Angelina Michalek / Anthony Michalek (Codetoil)<br>
 * <br>
 * This file is part of Curved Spacetime<br>
 * <br>
 * This program is free software: you can redistribute it and/or modify <br>
 * it under the terms of the GNU General Public License as published by <br>
 * the Free Software Foundation, either version 3 of the License, or <br>
 * (at your option) any later version.<br>
 * <br>
 * This program is distributed in the hope that it will be useful,<br>
 * but WITHOUT ANY WARRANTY; without even the implied warranty of<br>
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the<br>
 * GNU General Public License for more details.<br>
 * <br>
 * You should have received a copy of the GNU General Public License<br>
 * along with this program.  If not, see <a href="https://www.gnu.org/licenses/">https://www.gnu.org/licenses/</a>.<br>
 */

/**
 * API Module of Curved Spacetime
 *
 */
module io.codetoil.curved_spacetime.api {
	requires java.logging;
	exports io.codetoil.curved_spacetime.loader;
	exports io.codetoil.curved_spacetime.loader.entrypoint;
	exports io.codetoil.curved_spacetime.api;
	exports io.codetoil.curved_spacetime.api.scene;
}

A.2 io/codetoil/curved_spacetime/api/Engine.java

/**
 * Curved Spacetime is a work-in-progress easy-to-use modular simulator for General Relativity.<br>
 * Copyright (C) 2023-2026 Angelina Michalek / Anthony Michalek (Codetoil)<br>
 * <br>
 * This file is part of Curved Spacetime<br>
 * <br>
 * This program is free software: you can redistribute it and/or modify <br>
 * it under the terms of the GNU General Public License as published by <br>
 * the Free Software Foundation, either version 3 of the License, or <br>
 * (at your option) any later version.<br>
 * <br>
 * This program is distributed in the hope that it will be useful,<br>
 * but WITHOUT ANY WARRANTY; without even the implied warranty of<br>
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the<br>
 * GNU General Public License for more details.<br>
 * <br>
 * You should have received a copy of the GNU General Public License<br>
 * along with this program.  If not, see <a href="https://www.gnu.org/licenses/">https://www.gnu.org/licenses/</a>.<br>
 */

package io.codetoil.curved_spacetime.api;

import io.codetoil.curved_spacetime.api.scene.Scene;
import io.codetoil.curved_spacetime.api.scene.SceneCallback;
import io.codetoil.curved_spacetime.loader.CurvedSpacetimeLoader;

import java.util.concurrent.CompletableFuture;
import java.util.function.Consumer;
import java.util.function.Function;
import java.util.logging.ConsoleHandler;
import java.util.logging.Level;
import java.util.logging.Logger;

/**
 * The engine: it owns the configuration, the scenes, and the callback loop, and it drives module initialization.
 * <p>
 * Constructing an engine is what starts the program: an implementation's constructor loads the main configuration,
 * registers the initial scene, runs every module's {@code main} entrypoint, and then begins the callback loop — so by
 * the time it returns, the whole module graph is up.
 * <p>
 * Callbacks all run on a single scheduled thread, so implementations need no synchronisation against one another.
 * Module initialization is the opposite: entrypoints run concurrently on an unbounded pool, which the dependency
 * handshake requires — see {@link #callDependents(String, Class, Consumer, Logger)}.
 */
public abstract class Engine
{
	/**
	 * The loader module entrypoints are resolved through.
	 */
	protected final CurvedSpacetimeLoader loader;

	/**
	 * Creates an engine that resolves module entrypoints through the given loader.
	 *
	 * @param loader
	 * 		the loader module entrypoints are resolved through
	 */
	public Engine(CurvedSpacetimeLoader loader)
	{
		this.loader = loader;
	}

	/**
	 * Adds a scene and gives every registered generator a callback for it.
	 *
	 * @param scene
	 * 		the scene to add
	 */
	public abstract void registerScene(Scene scene);

	/**
	 * Invokes every entrypoint registered under the given name, concurrently, and waits for all of them.
	 * <p>
	 * The pool this uses is unbounded, and must remain so. The dependency handshake blocks a consumer in
	 * {@code TransferQueue.take} while its producer is still to run, so a producer and its consumer have to be runnable
	 * at the same time; a bounded pool deadlocks as soon as its threads fill with consumers whose producers are still
	 * queued.
	 * <p>
	 * The first entrypoint to fail aborts the whole call rather than leaving a half-initialized module graph running.
	 *
	 * @param <E>
	 * 		the entrypoint type
	 * @param name
	 * 		the entrypoint name to invoke, such as {@code main}
	 * @param moduleInitializerClass
	 * 		the type registered entrypoints must be assignable to
	 * @param onInitialize
	 * 		the action to apply to each entrypoint
	 * @param logger
	 * 		the logger to trace dispatch through
	 *
	 * @throws Throwable
	 * 		whatever the first failing entrypoint threw
	 */
	public abstract <E> void callDependents(String name,
											Class<E> moduleInitializerClass,
											Consumer<E> onInitialize,
											Logger logger) throws Throwable;

	/**
	 * Prepares the loader and runs every module's {@code main} entrypoint.
	 *
	 * @throws RuntimeException
	 * 		wrapping whatever a module's entrypoint threw
	 */
	public abstract void runEntrypoints();

	/**
	 * Returns the loader this engine resolves entrypoints through.
	 *
	 * @return the loader
	 */
	public CurvedSpacetimeLoader getCurvedSpacetimeLoader()
	{
		return this.loader;
	}

	/**
	 * Registers scene-independent work and initialises it on the callback thread.
	 *
	 * @param mainCallback
	 * 		the callback to register
	 *
	 * @return the completable future generated for this task
	 */
	public abstract CompletableFuture<Void> registerMainCallback(MainCallback mainCallback);

	/**
	 * Registers a factory that produces one callback per scene.
	 * <p>
	 * The generator is applied to every scene that exists now, and to each one registered later, so a module never has
	 * to track scenes itself.
	 *
	 * @param sceneCallbackGenerator
	 * 		the factory producing a callback for a given scene
	 *
	 * @return the completable future generated for this task
	 */
	public abstract CompletableFuture<Void> registerSceneCallbackGenerator(
			Function<Scene, SceneCallback> sceneCallbackGenerator);

	/**
	 * Stops the callback loop, releases every callback, and then shuts the callback executor down.
	 */
	public abstract void clean();

	/**
	 * Logs a failure at {@code SEVERE} and stops the engine.
	 *
	 * @param t
	 * 		the failure to log
	 * @param message
	 * 		the message to log it with
	 */
	public abstract void throwError(Throwable t, String message);

	/**
	 * Returns the console handler used for the Curved Spacetime Loggers.
	 *
	 * @return the console handler
	 */
	public abstract ConsoleHandler getConsoleHandler();

	/**
	 * Returns whether this engine has finished initializing.
	 * <p>
	 * That does not mean every callback is registered: a callback can be registered at any time, and registration is
	 * asynchronous.
	 *
	 * @return {@code true} if the engine is initialized
	 */
	public abstract boolean isInitialized();

	/**
	 * Returns the level every module logger is set to.
	 *
	 * @return the logger level from this engine's configuration
	 */
	public abstract Level getLoggerLevel();

	/**
	 * Returns how many times per second the callback loop runs.
	 *
	 * @return the configured frame rate, in frames per second
	 */
	public abstract int getFPS();
}

A.3 io/codetoil/curved_spacetime/api/MainCallback.java

/**
 * Curved Spacetime is a work-in-progress easy-to-use modular simulator for General Relativity.<br>
 * Copyright (C) 2023-2026 Angelina Michalek / Anthony Michalek (Codetoil)<br>
 * <br>
 * This file is part of Curved Spacetime<br>
 * <br>
 * This program is free software: you can redistribute it and/or modify <br>
 * it under the terms of the GNU General Public License as published by <br>
 * the Free Software Foundation, either version 3 of the License, or <br>
 * (at your option) any later version.<br>
 * <br>
 * This program is distributed in the hope that it will be useful,<br>
 * but WITHOUT ANY WARRANTY; without even the implied warranty of<br>
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the<br>
 * GNU General Public License for more details.<br>
 * <br>
 * You should have received a copy of the GNU General Public License<br>
 * along with this program.  If not, see <a href="https://www.gnu.org/licenses/">https://www.gnu.org/licenses/</a>.<br>
 */

package io.codetoil.curved_spacetime.api;

/**
 * Work the engine runs once at start-up and then repeatedly, independent of any scene.
 * <p>
 * A module registers one of these with {@link Engine#registerMainCallback(MainCallback)}. The engine calls
 * {@link #init()} once, then {@link #loop()} at the configured frame rate, and {@link #clean()} on shutdown. All three
 * run on the engine's single callback thread, so an implementation may hold mutable state without synchronising it
 * against the other callbacks.
 */
public abstract class MainCallback
{
	/**
	 * The engine this callback belongs to.
	 */
	protected final Engine engine;

	/**
	 * Whether this callback has finished setting itself up.
	 * <p>
	 * Deliberately not maintained by this class. An implementation sets this to {@code true} from its own
	 * {@link #init()}, at the point where its setup is genuinely complete — only the implementation knows when that
	 * is.
	 */
	protected boolean initialized = false;

	/**
	 * Creates a callback bound to the given engine.
	 *
	 * @param engine
	 * 		the engine this callback belongs to
	 */
	protected MainCallback(Engine engine)
	{
		this.engine = engine;
	}

	/**
	 * Returns whether this callback has finished setting itself up.
	 *
	 * @return {@code true} once the implementation has flagged its own setup complete
	 */
	public boolean isInitialized()
	{
		return this.initialized;
	}

	/**
	 * Sets this callback up.
	 * <p>
	 * Called once, before the first {@link #loop()}. An implementation should set {@link #initialized} when it
	 * finishes.
	 */
	public abstract void init();

	/**
	 * Advances this callback by one frame.
	 * <p>
	 * Called repeatedly at the frame rate the engine's configuration specifies.
	 */
	public abstract void loop();

	/**
	 * Releases whatever this callback acquired in {@link #init()}.
	 */
	public abstract void clean();
}

A.4 io/codetoil/curved_spacetime/api/scene/Scene.java

/**
 * Curved Spacetime is a work-in-progress easy-to-use modular simulator for General Relativity.<br>
 * Copyright (C) 2023-2026 Angelina Michalek / Anthony Michalek (Codetoil)<br>
 * <br>
 * This file is part of Curved Spacetime<br>
 * <br>
 * This program is free software: you can redistribute it and/or modify <br>
 * it under the terms of the GNU General Public License as published by <br>
 * the Free Software Foundation, either version 3 of the License, or <br>
 * (at your option) any later version.<br>
 * <br>
 * This program is distributed in the hope that it will be useful,<br>
 * but WITHOUT ANY WARRANTY; without even the implied warranty of<br>
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the<br>
 * GNU General Public License for more details.<br>
 * <br>
 * You should have received a copy of the GNU General Public License<br>
 * along with this program.  If not, see <a href="https://www.gnu.org/licenses/">https://www.gnu.org/licenses/</a>.<br>
 */

package io.codetoil.curved_spacetime.api.scene;

/**
 * One independent thing being simulated and drawn.
 * <p>
 * The engine holds a list of these and pairs each with a {@link SceneCallback} per registered generator, so modules act
 * on scenes without tracking them. A scene currently carries no state of its own: what a scene <em>contains</em> —
 * spacetimes, metrics, worldlines — belongs to the simulation model, which has not been settled yet and is deliberately
 * outside the scope of this API.
 */
public class Scene
{
	/**
	 * Creates an empty scene.
	 */
	public Scene()
	{
	}
}

A.5 io/codetoil/curved_spacetime/api/scene/SceneCallback.java

/**
 * Curved Spacetime is a work-in-progress easy-to-use modular simulator for General Relativity.<br>
 * Copyright (C) 2023-2026 Angelina Michalek / Anthony Michalek (Codetoil)<br>
 * <br>
 * This file is part of Curved Spacetime<br>
 * <br>
 * This program is free software: you can redistribute it and/or modify <br>
 * it under the terms of the GNU General Public License as published by <br>
 * the Free Software Foundation, either version 3 of the License, or <br>
 * (at your option) any later version.<br>
 * <br>
 * This program is distributed in the hope that it will be useful,<br>
 * but WITHOUT ANY WARRANTY; without even the implied warranty of<br>
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the<br>
 * GNU General Public License for more details.<br>
 * <br>
 * You should have received a copy of the GNU General Public License<br>
 * along with this program.  If not, see <a href="https://www.gnu.org/licenses/">https://www.gnu.org/licenses/</a>.<br>
 */

package io.codetoil.curved_spacetime.api.scene;

import io.codetoil.curved_spacetime.api.Engine;

/**
 * Work the engine runs once at start-up and then repeatedly, against one particular scene.
 * <p>
 * A module does not register these directly. It registers a generator with
 * {@link Engine#registerSceneCallbackGenerator}, and the engine applies that generator to every scene, so a module that
 * wants to act on scenes gets one callback per scene without having to track scenes itself.
 * <p>
 * The engine calls {@link #init()} once, then {@link #loop()} at the configured frame rate, and {@link #clean()} on
 * shutdown, all on its single callback thread.
 */
public abstract class SceneCallback
{
	/**
	 * The engine this callback belongs to.
	 */
	protected final Engine engine;

	/**
	 * The scene this callback acts on.
	 */
	protected final Scene scene;

	/**
	 * Whether this callback has finished setting itself up.
	 * <p>
	 * Deliberately not maintained by this class. An implementation sets this to {@code true} from its own
	 * {@link #init()}, at the point where its setup is genuinely complete — only the implementation knows when that
	 * is.
	 */
	protected boolean initialized = false;

	/**
	 * Creates a callback bound to the given engine and scene.
	 *
	 * @param engine
	 * 		the engine this callback belongs to
	 * @param scene
	 * 		the scene this callback acts on
	 */
	protected SceneCallback(Engine engine, Scene scene)
	{
		this.engine = engine;
		this.scene = scene;
	}

	/**
	 * Returns whether this callback has finished setting itself up.
	 *
	 * @return {@code true} once the implementation has flagged its own setup complete
	 */
	public boolean isInitialized()
	{
		return this.initialized;
	}

	/**
	 * Sets this callback up against its scene.
	 * <p>
	 * Called once, before the first {@link #loop()}. An implementation should set {@link #initialized} when it
	 * finishes.
	 */
	public abstract void init();

	/**
	 * Advances this callback by one frame.
	 * <p>
	 * Called repeatedly at the frame rate the engine's configuration specifies.
	 */
	public abstract void loop();

	/**
	 * Releases whatever this callback acquired in {@link #init()}.
	 */
	public abstract void clean();
}

A.6 io/codetoil/curved_spacetime/loader/CurvedSpacetimeLoader.java

/**
 * Curved Spacetime is a work-in-progress easy-to-use modular simulator for General Relativity.<br>
 * Copyright (C) 2025-2026 Angelina Michalek / Anthony Michalek (Codetoil)<br>
 * <br>
 * This file is part of Curved Spacetime<br>
 * <br>
 * This program is free software: you can redistribute it and/or modify <br>
 * it under the terms of the GNU General Public License as published by <br>
 * the Free Software Foundation, either version 3 of the License, or <br>
 * (at your option) any later version.<br>
 * <br>
 * This program is distributed in the hope that it will be useful,<br>
 * but WITHOUT ANY WARRANTY; without even the implied warranty of<br>
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the<br>
 * GNU General Public License for more details.<br>
 * <br>
 * You should have received a copy of the GNU General Public License<br>
 * along with this program.  If not, see <a href="https://www.gnu.org/licenses/">https://www.gnu.org/licenses/</a>.<br>
 */

package io.codetoil.curved_spacetime.loader;

import io.codetoil.curved_spacetime.api.Engine;

import java.nio.file.Path;
import java.util.List;
import java.util.function.Consumer;

/**
 * Discovers modules and resolves their entrypoints on the engine's behalf.
 * <p>
 * An implementation is free to resolve entrypoints however it likes. The closed-world loader holds them in static
 * tables so that GraalVM native-image can reach them by ordinary static analysis; the Quilt loader delegates to Quilt
 * Loader, which discovers them dynamically. Neither strategy is privileged by this interface.
 * <p>
 * Implementations must satisfy requirements R6 through R11.
 */
public interface CurvedSpacetimeLoader
{
	/**
	 * Prepares this loader for module initialization.
	 * <p>
	 * The engine calls this exactly once, before invoking any entrypoint. An implementation must retain {@code engine}
	 * such that {@link #getEngine()} returns it thereafter.
	 *
	 * @param path
	 * 		the run directory modules resolve their resources against
	 * @param engine
	 * 		the engine driving initialization
	 */
	void prepareModInit(Path path, Engine engine);

	/**
	 * Returns every entrypoint registered under the given name whose runtime type is assignable to
	 * {@code moduleInitializerClass}.
	 * <p>
	 * An implementation returns the same instances across repeated calls within one run. The dependency handshake
	 * relies on that: a dependent locates its own main entrypoint by filtering this list, then transfers to the queue
	 * owned by that exact object.
	 *
	 * @param <E>
	 * 		the entrypoint type
	 * @param name
	 * 		the entrypoint name, such as {@code main}
	 * @param moduleInitializerClass
	 * 		the type registered entrypoints must be assignable to
	 *
	 * @return the matching entrypoints, empty when the name is recognised but nothing is registered
	 *
	 * @throws IllegalArgumentException
	 * 		if the entrypoint name is not recognised
	 */
	<E> List<E> getEntrypoints(String name, Class<E> moduleInitializerClass);

	/**
	 * Applies the given consumer to every entrypoint {@link #getEntrypoints} would return for the same arguments.
	 * <p>
	 * No ordering is imposed, and callers must not depend on one.
	 *
	 * @param <E>
	 * 		the entrypoint type
	 * @param name
	 * 		the entrypoint name, such as {@code main}
	 * @param moduleInitializerClass
	 * 		the type registered entrypoints must be assignable to
	 * @param moduleInitializerConsumer
	 * 		the action to apply to each entrypoint
	 *
	 * @throws IllegalArgumentException
	 * 		if the entrypoint name is not recognised
	 */
	<E> void invokeEntrypoints(String name, Class<E> moduleInitializerClass,
							   Consumer<? super E> moduleInitializerConsumer);

	/**
	 * Returns the engine this loader was prepared with.
	 *
	 * @return the engine passed to {@link #prepareModInit}, or {@code null} before that call
	 */
	Engine getEngine();
}

A.7 io/codetoil/curved_spacetime/loader/entrypoint/ModuleConfig.java

/**
 * Curved Spacetime is a work-in-progress easy-to-use modular simulator for General Relativity.<br>
 * Copyright (C) 2025-2026 Angelina Michalek / Anthony Michalek (Codetoil)<br>
 * Copyright (c) 2025 Antonio Hernández Bejarano<br>
 * <br>
 * This file is part of Curved Spacetime<br>
 * <br>
 * This program is free software: you can redistribute it and/or modify <br>
 * it under the terms of the GNU General Public License as published by <br>
 * the Free Software Foundation, either version 3 of the License, or <br>
 * (at your option) any later version.<br>
 * <br>
 * This program is distributed in the hope that it will be useful,<br>
 * but WITHOUT ANY WARRANTY; without even the implied warranty of<br>
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the<br>
 * GNU General Public License for more details.<br>
 * <br>
 * You should have received a copy of the GNU General Public License<br>
 * along with this program.  If not, see <a href="https://www.gnu.org/licenses/">https://www.gnu.org/licenses/</a>.<br>
 */

package io.codetoil.curved_spacetime.loader.entrypoint;

import java.io.IOException;

/**
 * A module's persisted settings, backed by a {@code java.util.Properties} file under {@code config/}.
 * <p>
 * A configuration is never allowed to fail because its file is absent or incomplete. Loading substitutes a documented
 * default for every key it cannot read, records that it did so, and the owning module then writes the completed file
 * back:
 * <pre>{@code
 * this.config = new XModuleConfig(this.logger).load();
 * if (this.config.isDirty()) this.config.save();
 * }</pre>
 * <p>
 * Implementations must satisfy requirements R31 through R37.
 */
public interface ModuleConfig
{
	/**
	 * Reads this configuration from disk, substituting defaults for anything missing or invalid.
	 * <p>
	 * An absent file is not an error. For each key that is missing or fails to parse, an implementation logs a warning
	 * identifying the key and the accepted range, substitutes the documented default, and sets the dirty flag.
	 *
	 * @return this configuration, so that construction and loading compose
	 *
	 * @throws IOException
	 * 		if the file exists but cannot be read
	 */
	ModuleConfig load() throws IOException;

	/**
	 * Writes this configuration to disk, creating {@code config/} if it does not exist.
	 * <p>
	 * Every known key is written, not only those that changed, so that a user who deletes the file gets a complete one
	 * back on the next run. The dirty flag is cleared on success.
	 *
	 * @throws IOException
	 * 		if the directory cannot be created or the file cannot be written
	 */
	void save() throws IOException;

	/**
	 * Returns whether this configuration differs from what is on disk.
	 * <p>
	 * Set whenever the in-memory state diverges from the file. {@link #load()} substituting a default for a missing or
	 * unparseable key is the usual cause, but any later change to a value counts equally. {@link #save()} clears it,
	 * since writing the file makes the two agree again.
	 *
	 * @return {@code true} if the file does not match this configuration and should be rewritten
	 */
	boolean isDirty();
}

A.8 io/codetoil/curved_spacetime/loader/entrypoint/ModuleDependentModuleInitializer.java

/**
 * Curved Spacetime is a work-in-progress easy-to-use modular simulator for General Relativity.<br>
 * Copyright (C) 2025-2026 Angelina Michalek / Anthony Michalek (Codetoil)<br>
 * <br>
 * This file is part of Curved Spacetime<br>
 * <br>
 * This program is free software: you can redistribute it and/or modify <br>
 * it under the terms of the GNU General Public License as published by <br>
 * the Free Software Foundation, either version 3 of the License, or <br>
 * (at your option) any later version.<br>
 * <br>
 * This program is distributed in the hope that it will be useful,<br>
 * but WITHOUT ANY WARRANTY; without even the implied warranty of<br>
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the<br>
 * GNU General Public License for more details.<br>
 * <br>
 * You should have received a copy of the GNU General Public License<br>
 * along with this program.  If not, see <a href="https://www.gnu.org/licenses/">https://www.gnu.org/licenses/</a>.<br>
 */
package io.codetoil.curved_spacetime.loader.entrypoint;

import io.codetoil.curved_spacetime.api.Engine;

/**
 * The callback by which one module learns of another module it depends on.
 * <p>
 * Each module extends this with a named interface of its own, and any module depending on that module registers an
 * implementation of it. When the depended-on module reaches the last step of its initialization, it invokes every such
 * implementation, passing itself and the engine. The implementation's job is to hand that entrypoint to its own module,
 * by transferring it into that module's {@link ModuleInitializer#getDependencyModuleTransferQueue() dependency queue}:
 * <pre>{@code
 * engine.getCurvedSpacetimeLoader()
 *         .getEntrypoints("main", ModuleInitializer.class).stream()
 *         .filter(MyModuleEntrypoint.class::isInstance)
 *         .findFirst().orElseThrow()
 *         .getDependencyModuleTransferQueue().transfer(moduleEntrypoint);
 * }</pre>
 * <p>
 * Implementations must satisfy requirements R17 through R19 and R25.
 *
 * @param <E>
 * 		the entrypoint type of the module being depended on
 */
public interface ModuleDependentModuleInitializer<E extends ModuleInitializer>
{
	/**
	 * Receives the entrypoint of a module this module depends on.
	 * <p>
	 * Called on the depended-on module's initialization thread, not this module's.
	 *
	 * @param moduleEntrypoint
	 * 		the entrypoint of the module being depended on
	 * @param engine
	 * 		the engine driving initialization
	 */
	void onInitialize(E moduleEntrypoint, Engine engine);
}

A.9 io/codetoil/curved_spacetime/loader/entrypoint/ModuleInitializer.java

/**
 * Curved Spacetime is a work-in-progress easy-to-use modular simulator for General Relativity.<br>
 * Copyright (C) 2023-2026 Angelina Michalek / Anthony Michalek (Codetoil)<br>
 * Copyright 2022, 2023 QuiltMC<br>
 * <br>
 * This file is part of Curved Spacetime<br>
 * <br>
 * This program is free software: you can redistribute it and/or modify <br>
 * it under the terms of the GNU General Public License as published by <br>
 * the Free Software Foundation, either version 3 of the License, or <br>
 * (at your option) any later version.<br>
 * <br>
 * This program is distributed in the hope that it will be useful,<br>
 * but WITHOUT ANY WARRANTY; without even the implied warranty of<br>
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the<br>
 * GNU General Public License for more details.<br>
 * <br>
 * You should have received a copy of the GNU General Public License<br>
 * along with this program.  If not, see <a href="https://www.gnu.org/licenses/">https://www.gnu.org/licenses/</a>.<br>
 */

package io.codetoil.curved_spacetime.loader.entrypoint;

import io.codetoil.curved_spacetime.api.Engine;

import java.util.concurrent.TransferQueue;
import java.util.logging.Logger;

/**
 * A module's {@code main} entrypoint, the object the engine drives during initialization.
 * <p>
 * Every module registers exactly one of these. The engine invokes {@link #onInitialize(Engine)} on all of them
 * concurrently, so a module must not assume anything about the order in which its peers come up; the only ordering
 * guarantee available is the one the dependency handshake provides.
 * <p>
 * Implementations must satisfy requirements R12 through R16.
 */
public interface ModuleInitializer
{
	/**
	 * Brings this module up.
	 * <p>
	 * An implementation sets its logger's level from the engine's configuration, loads its own configuration and saves
	 * it if loading substituted defaults, receives any dependencies it declares through
	 * {@link #getDependencyModuleTransferQueue()}, performs any operations it must perform during initialization, and
	 * finally invokes its own dependent entrypoints, passing itself and the engine.
	 *
	 * @param engine
	 * 		the engine driving initialization
	 */
	void onInitialize(Engine engine);

	/**
	 * Returns this module's configuration.
	 *
	 * @return the configuration, or {@code null} before {@link #onInitialize(Engine)} has loaded it
	 */
	ModuleConfig getConfig();

	/**
	 * Returns the logger this module writes its diagnostics to.
	 * <p>
	 * The same instance is returned for the lifetime of this entrypoint.
	 *
	 * @return this module's logger
	 */
	Logger getLogger();

	/**
	 * Returns the queue by which this module receives the entrypoints it depends on.
	 * <p>
	 * A module does not look its dependencies up. Each module it depends on invokes a dependent entrypoint, which
	 * transfers that module's own entrypoint into this queue. The same instance is returned for the lifetime of this
	 * entrypoint; a fresh or defensively copied queue breaks the handshake, because the producer transfers into
	 * whichever queue this method returned.
	 *
	 * @return this module's dependency transfer queue
	 */
	TransferQueue<ModuleInitializer> getDependencyModuleTransferQueue();
}