Class LPCRuntime

java.lang.Object
io.github.protasm.jvmud.compiler.exec.LPCRuntime
public final class LPCRuntime extends Object
Host-facing LPC execution runtime that owns classloading, object identity, and runtime context.

This runtime is distinct from io.github.protasm.jvmud.compiler.runtime, which contains the language-level helpers used by generated bytecode. LPCRuntime sits above the compiler pipeline and provides a minimal API for loading LPC objects from source code.

The runtime registers shared objects before running compiler-generated LPC initialization so benign circular singleton references can resolve an in-progress object. Direct recursive load re-entry that cannot be resolved through a registered object still fails with a clear LPCRuntimeException.

Usage example:

LPCRuntime runtime = new LPCRuntime(LPCRuntimeConfig.builder()
        .baseIncludePath(Path.of("mudlibs", "lp245"))
        .build());
LPCObjectHandle orc = runtime.load("/obj/orc.c");
runtime.withRuntimeContext(() -> {
    orc.instance().getClass().getMethod("init").invoke(orc.instance());
    return null;
});

  • Constructor Details

  • Method Details

    • load

      public LPCObjectHandle load(String sourcePath)
      Loads, compiles, instantiates, registers, and initializes one LPC source file.

      Relative paths are resolved under the configured base include path. Absolute-looking mudlib paths such as /room/church are also resolved under that base path when one is configured.

    • loadOrGetObject

      public Object loadOrGetObject(String sourcePath)
      Returns a registered shared object for a source path, loading it if needed.

      This is the host-side equivalent of resolving a mudlib singleton object rather than making a clone.

    • reload

      public LPCObjectHandle reload(String sourcePath)
      Reloads an LPC source path, replacing the shared registered object if it already exists.

    • reload

      public LPCObjectHandle reload(Path sourcePath)
      Reloads a source file from a filesystem path.

      Reloading creates a fresh class loader because generated JVM classes cannot be redefined in the same loader.

    • load

      public LPCObjectHandle load(Path sourcePath)
      Loads, compiles, instantiates, registers, and initializes one source file.

    • compile

      public CompilationResult compile(Path sourcePath)
      Compiles one source file using this runtime's include, efun, and mudlib boundary context.

    • tryLoad

      public LPCLoadResult tryLoad(String sourcePath)
      Attempts to load source and captures runtime failures as a result object.

    • tryLoad

      public LPCLoadResult tryLoad(Path sourcePath)
      Attempts to load source and captures runtime failures as a result object.

    • loadSource

      public LPCObjectHandle loadSource(String sourceName, String source)
      Compiles and loads in-memory LPC source under the supplied source name.

    • cloneObject

      public Object cloneObject(String sourcePath)
      Creates a new clone of a compiled LPC object.

      The source class is compiled if needed. Each clone receives a unique runtime object id using the canonical source id plus an always-numbered #cloneN suffix.

    • moveObject

      public void moveObject(Object object, Object destination)
      Moves one runtime object into another object or into the shared object named by a path.

    • environment

      public Object environment(Object object)
      Returns the immediate runtime environment/container for an object.

    • present

      public Object present(Object identifier, Object container)
      Resolves an object by identifier in a container, using current-context defaults when needed.

    • firstInventory

      public Object firstInventory(Object container)
      Returns the first object contained by a runtime object.

    • nextInventory

      public Object nextInventory(Object object)
      Returns the next sibling object in inventory traversal.

    • destructObject

      public void destructObject(Object object)
      Destructs a runtime object and removes it from object identity and containment indexes.

    • registerHostObject

      public void registerHostObject(String objectId, Object object)
      Registers a host-created object under a mudlib-style object id.

    • objectId

      public String objectId(Object object)
      Returns the registered object id for an object, or null if it is not registered.

    • readMudlibText

      public Object readMudlibText(String path)
      Reads a mudlib-relative text file, returning LPC false (0) when unavailable.

    • listMudlibPaths

      public Object listMudlibPaths(String path, int flags)
      Lists mudlib-rooted files using the common LP get_dir() flag shape.

      The initial JVMud contract supports the startup-critical name listing behavior: literal paths or single-segment globs such as /dir/*.sql, sorted unless the unsorted bit is set, and path-qualified names when the GETDIR_PATH bit is set. Metadata flags are intentionally left for later expansion.

    • appendMudlibText

      public int appendMudlibText(String path, Object text)
      Appends text to a mudlib-rooted file, returning LP-style success.

    • removeMudlibText

      public int removeMudlibText(String path)
      Removes a mudlib-rooted text or storage file, returning LP-style success.

    • copyMudlibText

      public int copyMudlibText(String source, String destination)
      Copies a mudlib-rooted file, returning LDMud-style zero for success.

    • renameMudlibText

      public int renameMudlibText(String source, String destination)
      Renames a mudlib-rooted file or directory, returning LDMud-style zero for success.

    • createMudlibDirectory

      public int createMudlibDirectory(String path)
      Creates a mudlib-rooted directory, returning LP-style success.

    • removeMudlibDirectory

      public int removeMudlibDirectory(String path)
      Removes an empty mudlib-rooted directory, returning LP-style success.

    • saveLPCObjectState

      public int saveLPCObjectState(String path, Object object)
      Saves scalar LPC object fields to mudlib-rooted storage, returning LP-style success.

    • restoreLPCObjectState

      public int restoreLPCObjectState(String path, Object object)
      Restores scalar LPC object fields from mudlib-rooted storage, returning LP-style success.

    • mudlibBoundary

      public MudlibBoundary mudlibBoundary()
      Returns the active mudlib boundary metadata.

    • registerMudlibBoundary

      public void registerMudlibBoundary(MudlibBoundary mudlibBoundary)
      Registers mudlib boundary metadata and updates generated-code helper configuration.

    • setScheduler

      public void setScheduler(WorldScheduler scheduler)
      Connects this LPC runtime to the deterministic scheduler for its owning world.

    • invokeObject

      public Object invokeObject(Object object, String methodName, Object... args)
      Invokes a public LPC method with this runtime installed as the current generated-code context.

    • invokeOptionalObject

      public Object invokeOptionalObject(Object object, String methodName, Object... args)
      Invokes a public LPC method when present, returning 0 if the object does not implement it.

    • refreshCommandActions

      public void refreshCommandActions(Object actor)
      Rebuilds command actions for a Persona from nearby mudlib objects.

      This invokes the configured interaction-scope lifecycle method on the Persona, its environment, and immediately nearby inventory objects so LPC init/add_action style registrations can be refreshed.

    • dispatchCommand

      public Object dispatchCommand(Object actor, String commandLine)
      Dispatches one player command line through the Persona's registered command actions.

    • withCommandActor

      public <T> T withCommandActor(Object actor, Supplier<T> action)
      Runs an operation with the supplied object as the active command actor.

    • hasCapturedSessionInput

      public boolean hasCapturedSessionInput(Object persona)
      Returns whether a persona is waiting for captured session input.

    • capturedSessionInputNoEcho

      public boolean capturedSessionInputNoEcho(Object persona)
      Returns whether the pending captured input should suppress terminal echo.

    • deliverCapturedSessionInput

      public Object deliverCapturedSessionInput(Object persona, String line)
      Delivers one captured input line to a persona.

    • inspectObject

      public LPCObjectInspection inspectObject(Object object)
      Builds a reflection-backed inspection snapshot for admin tooling.

    • registerEfun

      public void registerEfun(Efun efun)
      Registers one LPC-facing engine function in this runtime.

    • setPlayerTransferHandler

      public void setPlayerTransferHandler(BiFunction<Object,String,Integer> playerTransferHandler)
      Sets the server-owned handler for moving the active Player between hosted games.

    • setOutputSink

      public void setOutputSink(Consumer<String> outputSink)
      Sets the default output sink used for runtime text delivery.

    • bindPlayerSession

      public void bindPlayerSession(String sessionId, String remoteAddress, Consumer<String> sessionOutputSink)
      Binds a host session id to an engine Player before a Persona has been resolved.

    • bindSession

      public void bindSession(String sessionId, Object persona, String remoteAddress, Consumer<String> sessionOutputSink)
      Binds a host session id to a persona and session-specific output sink.

    • bindSession

      public void bindSession(String sessionId, Object persona, String remoteAddress, Consumer<String> sessionOutputSink, MudlibProjection mudlibProjection)
      Binds a host session id to a persona with an explicit mudlib compatibility projection.

    • rebindSessionLpcObject

      public boolean rebindSessionLpcObject(Object newObject, Object oldObject)
      Rebinds an existing host session from one LPC object to another.

      The host session and engine Player record remain stable; only the mudlib-facing object that receives commands and output changes.

    • unbindSession

      public void unbindSession(String sessionId)
      Removes a host session binding.

    • sessionRecord

      public Optional<SessionRecord> sessionRecord(String sessionId)
      Returns the engine-owned Session record for a bound host session.

    • lpcObjectForSession

      public Optional<Object> lpcObjectForSession(String sessionId)
      Returns the LPC object currently bound to a host session, when one exists.

    • isInteractive

      public boolean isInteractive(Object user)
      Returns true when the supplied LPC object is currently attached to a host session.

    • playerRecordForSession

      public Optional<PlayerRecord> playerRecordForSession(String sessionId)
      Returns the engine-owned Player record associated with a bound host session.

    • personaRecordForProjection

      public Optional<PersonaRecord> personaRecordForProjection(Object persona)
      Returns the engine-owned Persona record associated with a compatibility persona projection.

    • writeToSession

      public boolean writeToSession(SessionId sessionId, Object value)
      Writes engine control-plane or transport text to one bound Session.

    • writeToPlayer

      public boolean writeToPlayer(PlayerId playerId, Object value)
      Writes engine control-plane text to all active Sessions for one Player.

    • writeToPersona

      public boolean writeToPersona(PersonaId personaId, Object value)
      Writes engine gameplay text to one bound Persona.

    • outputTranscript

      public String outputTranscript()
      Returns the accumulated default output transcript for diagnostics and tests.

    • clearOutputTranscript

      public void clearOutputTranscript()
      Clears the accumulated default output transcript.

    • withRuntimeContext

      public <T> T withRuntimeContext(Supplier<T> action)
      Runs an action with this runtime installed as the current generated-code context.

    • withCurrentObject

      public <T> T withCurrentObject(Object object, Supplier<T> action)
      Runs an action with this runtime and a current LPC object installed.

    • runWithCurrentObject

      public void runWithCurrentObject(Object object, Runnable action)
      Runnable convenience wrapper for withCurrentObject(Object, Supplier).

    • runWithRuntimeContext

      public void runWithRuntimeContext(Runnable action)
      Runnable convenience wrapper for withRuntimeContext(Supplier).