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. This document is for the authors of modules and of loaders. It specifies what a conforming module and a conforming loader must do: the names a module must adopt, the order of its initialization, the handshake by which one module obtains a reference to another, its configuration, its manifest, and its callbacks.
It is complete on its own. Everything a module or a loader compiles against is reproduced in
Appendix A, and every requirement that binds a module or a loader is stated
here, so a third party can implement either without reading any other document or the engine's
source. Two loaders exist today and are cited throughout as reference implementations:
CurvedSpacetimeLoaderClosedLoader, which resolves entrypoints from static tables
compiled into the image, and CurvedSpacetimeLoaderQuiltLoader, which delegates to
Quilt Loader.
What a module computes is deliberately out of scope.
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.
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 neither modules nor loaders, and a requirement that binds more than one kind
of implementation carries the same number and wording wherever it appears.
A conforming module is a JPMS module that satisfies every requirement in §4, §6, §7, §8, and §10, and, when loaded by a Quilt-based loader, §9.
A conforming loader is an implementation of
io.codetoil.curved_spacetime.loader.CurvedSpacetimeLoader that satisfies every
requirement in §5.
A conforming loader is not required to use Quilt or to discover modules dynamically. Static resolution is explicitly permitted; see R7.
Engine. It passes itself to the loader's
prepareModInit, invokes every module's main entrypoint, and, once initialization
is complete, runs the modules' callbacks.
CurvedSpacetimeLoader. It maps an entrypoint name and type
to a list of entrypoint instances.
curved-spacetime-render-module.
curved-spacetime-render-glfw-module.
curved-spacetime-render-glfw-module the module key is
curved-spacetime-render-glfw-module. Several other names derive from it.
ModuleInitializer, registered under the entrypoint
name main.
MainCallback, or a SceneCallback bound to one scene: module code
the engine runs once initialization is complete.
init,
loop, and clean.
R1. A module's directory name MUST match
the associated module key, and the module key MUST end in
-module.
R2. An implementation module's JPMS module name MUST be its
API module's name extended by exactly one segment naming the implementation. The segment MUST use
snake_case where the implementation name is compound.
| Directory | JPMS module |
|---|---|
curved-spacetime-render-module |
io.codetoil.curved_spacetime.render |
curved-spacetime-render-glfw-module |
io.codetoil.curved_spacetime.render.glfw |
curved-spacetime-render-vulkan-module |
io.codetoil.curved_spacetime.render.vulkan |
curved-spacetime-render-vulkan-glfw-module |
io.codetoil.curved_spacetime.render.vulkan_glfw |
R3. A module MUST include an associated dependent entrypoint.
R4. A module MUST export its own package and its .entrypoint
subpackage.
R5. Names derived from the module key MUST be formed as
follows, where key is the module key and key_ is the module key with every
- replaced by _:
| Derived name | Form | Example for curved-spacetime-render-glfw-module |
|---|---|---|
| Configuration file | config/<key>.config |
config/curved-spacetime-render-glfw-module.config |
| Dependent entrypoint name | <key_>_dependent |
curved_spacetime_render_glfw_module_dependent |
| Quilt mod id | <key> |
curved-spacetime-render-glfw-module |
| Quilt group | the JPMS module name | io.codetoil.curved_spacetime.render.glfw |
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.
R7. getEntrypoints MUST return every registered
entrypoint for the given name whose runtime type is assignable to
moduleInitializerClass. A loader MAY resolve these statically; it is not required to
scan the module path.
R8. getEntrypoints MUST return an empty list,
not null, when a recognised entrypoint name has no registrations.
R9. getEntrypoints SHOULD throw
IllegalArgumentException for an entrypoint name the loader does not recognise, and
the message SHOULD identify the name and the requested class. Silently returning an empty list
for an unknown name hides module wiring mistakes and is NOT RECOMMENDED.
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.
R11. A loader MUST return the same instance for a given
entrypoint across repeated getEntrypoints calls within one run. The handshake in
§7 depends on identity: a dependent locates its own main entrypoint by
filtering this list, and transfers to the queue owned by that exact object.
R12. Every module MUST register exactly one main entrypoint
under the name main, implementing ModuleInitializer.
R13. The main entrypoint class SHOULD be named
<X>ModuleEntrypoint, where <X> is the module key in
PascalCase with -module dropped.
R14. getLogger MUST return the same
Logger instance for the lifetime of the entrypoint, and that logger MUST be the one
the module writes its diagnostics to.
R15. getDependencyModuleTransferQueue MUST
return the same TransferQueue instance for the lifetime of the entrypoint. A fresh
or defensively copied queue breaks the handshake.
R16. getConfig MUST return the module's
configuration once onInitialize has loaded it. It MAY return null
before that point, and callers MUST NOT invoke it before the owning module has initialized.
R17. A module MUST publish an interface named
<Module>ModuleDependentModuleInitializer in its.entrypoint subpackage, extending
ModuleDependentModuleInitializer<<Module>ModuleEntrypoint>.
R18. A module B that depends on module A MUST register a class implementing A's dependent interface under A's dependent entrypoint name, as derived in R5.
R19. That class SHOULD be named
<Module A>ModuleDependent<Module B>ModuleEntrypoint.
For curved-spacetime-render-glfw-module depending on
curved-spacetime-render-module:
| Role | Name |
|---|---|
| Entrypoint name | curved_spacetime_render_module_dependent |
| Interface | io.codetoil.curved_spacetime.render.entrypoint.CurvedSpacetimeRenderModuleDependentModuleInitializer
|
| Implementation | io.codetoil.curved_spacetime.render.glfw.CurvedSpacetimeRenderModuleDependentCurvedSpacetimeRenderGLFWModuleEntrypoint
|
R23. A module's onInitialize MUST, in order:
getLoggerLevel(), add the engine's
console handler — getConsoleHandler() — to that logger, and stop the logger
forwarding to its parent handlers;
isDirty() reports the load
substituted defaults;
The engine's console handler is set to the configured level. Under the JDK's
default logging configuration the root logger's handler is at INFO, so a logger
whose level alone is set loses every record below INFO, and one that keeps its
parent handlers beside the engine's emits every record at INFO and above
twice.
R24. A module MUST NOT touch another module's state before completing step 3. Until the handshake returns, no ordering guarantee exists.
A module does not look up its dependencies. It is handed them, through a
TransferQueue it owns, by dependent entrypoints running on other threads.
When module A reaches step 4, it invokes every entrypoint registered under
<a_key>_dependent, passing its own main entrypoint and the engine. Module
B's implementation of that interface locates B's main entrypoint through
the engine's loader and transfers A into B's queue:
@Override
public void onInitialize(CurvedSpacetimeRenderModuleEntrypoint curvedSpacetimeRenderModuleEntrypoint,
Engine engine)
{
try
{
engine.getCurvedSpacetimeLoader()
.getEntrypoints("main", ModuleInitializer.class).stream()
.filter(CurvedSpacetimeRenderGLFWModuleEntrypoint.class::isInstance)
.findFirst().orElseThrow()
.getDependencyModuleTransferQueue().transfer(curvedSpacetimeRenderModuleEntrypoint);
} catch (InterruptedException e)
{
throw new RuntimeException(e);
}
}
Meanwhile B is blocked in step 3, taking one element per declared dependency and sorting them by type:
protected void receiveDependenciesFromTransferQueue() throws InterruptedException
{
for (int i = 0; i < DEPENDENCY_COUNT; i++)
{
ModuleInitializer moduleInitializer = this.dependencyModuleTransferQueue.take();
if (moduleInitializer instanceof CurvedSpacetimeRenderModuleEntrypoint curvedSpacetimeRenderModuleEntrypoint)
{
this.curvedSpacetimeRenderModuleEntrypoint = curvedSpacetimeRenderModuleEntrypoint;
}
// … one branch per declared dependency
}
}
R25. A dependent entrypoint MUST transfer the entrypoint
it was given into the queue returned by its own module's
getDependencyModuleTransferQueue().
R26. A module MUST consume exactly as many elements from its
queue as it has declared dependencies — no more, no fewer. Taking too few strands a producer
blocked in transfer; taking too many blocks the consumer forever.
R27. A module MUST classify received elements by runtime type, and MUST NOT rely on arrival order. The transfers originate on independent threads.
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.
R30. A module SHOULD derive its dependency count from its declared dependencies rather than hard-coding a literal, so that adding or removing a dependency cannot desynchronise the count from reality.
R31. A module's configuration MUST be stored at
config/<module key>.config, relative to the run directory, in
java.util.Properties text format.
R32. load() MUST return the receiver, so that
construction and loading compose as
new XModuleConfig(logger).load().
R33. load() MUST NOT fail when the file is
absent. It MUST substitute defaults for every key and set the dirty flag.
R34. For each key that is missing or fails to parse,
load() MUST: log a warning identifying the key, the offending value where one
exists, and the accepted range; substitute the documented default; and set the dirty flag.
R35. isDirty() MUST report whether the
configuration differs from what is on disk. Loading having substituted a default is the
usual cause, but any later change to a value MUST be reflected too, and
save() MUST clear it. The caller is expected to persist a configuration that
does not match its file:
this.config = new XModuleConfig(this.logger).load();
if (this.config.isDirty()) this.config.save();
R36. save() MUST create the
config/ directory if it does not exist, MUST write every key it knows — not only
those that changed — and MUST clear the dirty flag on success.
R37. A configuration file MUST be self-describing after a
save(): a user who deletes it MUST get a complete, commented file back on the next
run.
A saved configuration:
#Config for the Curved Spacetime Render GLFW Module.
#Thu Jul 09 12:45:03 EDT 2026
vsync=true
R38. Every module MUST ship
quilt.mod.json on its resource path, with schema_version 1.
R39. quilt_loader.id MUST equal the module's
directory name and quilt_loader.group MUST equal its JPMS module name, per
R5.
R40. The entrypoints object MUST contain a
main key naming the module's main entrypoint class,
and one key per dependency, named per R5 and naming the corresponding dependent entrypoint
class.
R41. depends MUST list every module named in
entrypoints, plus java. Theentrypoints map
and the depends array MUST agree; a dependent entrypoint
without a matching dependency is a conformance error.
{
"schema_version": 1,
"quilt_loader": {
"group": "io.codetoil.curved_spacetime.render.glfw",
"id": "curved-spacetime-render-glfw-module",
"version": "0.1.0-SNAPSHOT",
"intermediate_mappings": "net.fabricmc:intermediary",
"entrypoints": {
"main": "io.codetoil.curved_spacetime.render.glfw.CurvedSpacetimeRenderGLFWModuleEntrypoint",
"curved_spacetime_render_module_dependent":
"io.codetoil.curved_spacetime.render.glfw.CurvedSpacetimeRenderModuleDependentCurvedSpacetimeRenderGLFWModuleEntrypoint"
},
"depends": [
{ "id": "curved-spacetime-main-module", "versions": ">=0.1.0-SNAPSHOT" },
{ "id": "curved-spacetime-render-module","versions": ">=0.1.0-SNAPSHOT" },
{ "id": "java", "versions": ">=25" }
]
}
}
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.
Appendix A documents what else the engine guarantees a callback. These
requirements bind the module's side.
R49. A callback's clean MUST tolerate being
called after its own init threw part-way, releasing only what init
actually acquired. The engine follows a failed init with
clean.
R50. A module MAY call the engine's clean to
stop it, and MUST do so from the callback thread, as a render module's window does from its
loop when it closes. A module that needs to stop the engine from another thread
registers a main callback that calls clean from its loop.
Otherwise a callback's clean would run on that thread instead of the callback thread,
while the callback's loop may still be running.
<key>; JPMS name nested under its API's
(R1–R2)
.entrypoint subpackage
(R4)
main entrypoint implementing ModuleInitializer
(R12)
Logger and TransferQueue instances
(R14, R15)
onInitialize follows the four-step order (R23)config/<key>.config, defaults on absence, dirty-then-save
(R31–R37)
quilt.mod.json whose entrypoints and depends agree
(R38–R41)
clean survives a failed init
(R49)
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.
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;
}
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();
}
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();
}
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()
{
}
}
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();
}
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();
}
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();
}
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);
}
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();
}