Class RuntimeContext

java.lang.Object
io.github.protasm.jvmud.compiler.runtime.RuntimeContext
public final class RuntimeContext extends Object
Encapsulates runtime state required by compiled LPC code.

This context owns engine function registration, object lifecycle tracking, and include resolution configuration so the compiler and runtime no longer depend on global singletons.

  • Constructor Details

  • Method Details

    • includeResolver

      public IncludeResolver includeResolver()

    • setIncludeResolver

      public void setIncludeResolver(IncludeResolver includeResolver)

    • efunRegistry

      public EfunRegistry efunRegistry()

    • setWorldProjection

      public void setWorldProjection(MudlibWorldProjection worldProjection)
      Selects the native world projection that owns mudlib containment state.

      Hosted instances set this during boot before loading world objects. Compiler-only runtimes retain an isolated native world by default.

    • worldProjection

      public MudlibWorldProjection worldProjection()
      Returns the native world projection currently used for LPC containment operations.

    • newPreprocessor

      public Preprocessor newPreprocessor()

    • setParserOptions

      public void setParserOptions(ParserOptions parserOptions)
      Selects the parser profile used for runtime-loaded mudlib source.

    • parserOptions

      public ParserOptions parserOptions()
      Returns the parser profile used for runtime-loaded mudlib source.

    • registerEfun

      public void registerEfun(Efun efun)

    • setObjectFactory

      public void setObjectFactory(Function<String,Object> objectFactory)

    • setObjectLoader

      public void setObjectLoader(Function<String,Object> objectLoader)

    • setMudlibTextReader

      public void setMudlibTextReader(Function<String,Object> mudlibTextReader)

    • setMudlibJsonReader

      public void setMudlibJsonReader(Function<String,Object> mudlibJsonReader)
      Sets the host callback used to parse mudlib-owned JSON files.
      Parameters:
      mudlibJsonReader - host reader, or null to restore the unavailable reader

    • setMudlibJsonArrayReader

      public void setMudlibJsonArrayReader(MudlibJsonArrayReader mudlibJsonArrayReader)
      Sets the host callback used for bounded, structural reads of mudlib JSON arrays.
      Parameters:
      mudlibJsonArrayReader - host reader, or null to restore the unavailable reader

    • setMudlibPathLister

      public void setMudlibPathLister(BiFunction<String,Integer,Object> mudlibPathLister)
      Sets the host callback used by file-listing efuns to enumerate mudlib-rooted paths.

    • setMudlibTextAppender

      public void setMudlibTextAppender(BiFunction<String,Object,Integer> mudlibTextAppender)

    • setMudlibTextRemover

      public void setMudlibTextRemover(Function<String,Integer> mudlibTextRemover)

    • setMudlibTextCopier

      public void setMudlibTextCopier(BiFunction<String,String,Integer> mudlibTextCopier)

    • setMudlibTextRenamer

      public void setMudlibTextRenamer(BiFunction<String,String,Integer> mudlibTextRenamer)

    • setMudlibDirectoryCreator

      public void setMudlibDirectoryCreator(Function<String,Integer> mudlibDirectoryCreator)

    • setMudlibDirectoryRemover

      public void setMudlibDirectoryRemover(Function<String,Integer> mudlibDirectoryRemover)

    • setPlayerTransferHandler

      public void setPlayerTransferHandler(BiFunction<Object,String,Integer> playerTransferHandler)

    • setLPCObjectStateSaver

      public void setLPCObjectStateSaver(BiFunction<String,Object,Integer> lpcObjectStateSaver)

    • setLPCObjectStateRestorer

      public void setLPCObjectStateRestorer(BiFunction<String,Object,Integer> lpcObjectStateRestorer)

    • setTimedRuntimeErrorHandler

      public void setTimedRuntimeErrorHandler(RuntimeContext.TimedRuntimeErrorHandler timedRuntimeErrorHandler)

    • setObjectDestructionRequestedHandler

      public void setObjectDestructionRequestedHandler(Function<Object,Object> objectDestructionRequestedHandler)

    • registerInMemoryObjectSource

      public void registerInMemoryObjectSource(String objectPath, String source, String displayPath)
      Registers source text for an in-memory LPC object that may later serve as a global helper.

      Host APIs such as LPCRuntime.loadSource(...) can compile an LPC object without writing a corresponding .c file. Declaration-backed global lookup still needs source text to recover function signatures, so those hosts register the source here under the object's normalized mudlib path.

    • setMfunObjectPath

      @Deprecated(forRemoval=false) public void setMfunObjectPath(String mfunObjectPath)
      Deprecated.
      use setMudlibBoundary(MudlibBoundary) with MudlibBoundary.mudlibGlobalObjectPath() metadata.
      Sets the mudlib-owned global mfun object path used by older callers.

    • setMudlibBoundary

      public void setMudlibBoundary(MudlibBoundary mudlibBoundary)
      Sets active mudlib boundary metadata for generated-code helpers and compatibility lookup.

    • engineFunctionName

      public String engineFunctionName(String mudlibName)

    • setScheduler

      public void setScheduler(WorldScheduler scheduler)

    • setOutputSink

      public void setOutputSink(Consumer<String> outputSink)

    • write

      public void write(Object value)
      Writes text to the current execution recipient, or to the transcript in detached contexts.

    • writeToLpcObject

      public void writeToLpcObject(Object target, Object value)
      Writes text only to the target object's bound session.

      Unlike write(Object), this targeted write deliberately does not fall back to the ambient output transcript when the target is not interactive. If that target is later bound to a Session, JVMud flushes the pending text to the target's own output sink.

    • 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 the bound Session for one Persona.

    • emitPerceivable

      public void emitPerceivable(Object emitter, Object value)

    • emitPerceivableExcept

      public void emitPerceivableExcept(Object emitter, Object value, Object excluded)

    • emitPerceivableAt

      public void emitPerceivableAt(Object location, Object value)

    • outputTranscript

      public String outputTranscript()

    • clearOutputTranscript

      public void clearOutputTranscript()

    • resolveEfun

      public Efun resolveEfun(String name, int arity)

    • resolveEngineEfun

      public Efun resolveEngineEfun(String name, int arity)
      Resolves an engine efun without consulting mudlib compatibility functions.

      This is used for LPC efun::name(...) calls, where the source explicitly asks to bypass mudlib-level shadowing and invoke the JVMud-native engine function directly.

    • invokeEfun

      public Object invokeEfun(String name, int arity, Object[] args)
      Invokes a mudlib-visible function through the active compatibility boundary.

      Mfuns normally shadow engine efuns. When the mudlib profile maps a mudlib-visible name to an engine function and the call carries a first-class callable, the mapped engine function is allowed to run before a string-typed mfun wrapper can coerce the callable into display text.

    • registerObject

      public void registerObject(String name, Object object)
      Binds an engine object to a mudlib object path.

      An object has one canonical mudlib path for APIs such as file_name(). Rebinding removes the object's previous canonical path, and replacing an existing path clears the old occupant's reverse lookup. This lets a mudlib-created object serve a requested missing source path without retaining its temporary clone id as the canonical identity.

    • getObject

      public Object getObject(String name)

    • loadOrGetObject

      public Object loadOrGetObject(String name)

    • objectsView

      public Map<String,Object> objectsView()

    • objects

      public Map<String,Object> objects()

    • objectId

      public String objectId(Object object)

    • inheritedPrograms

      public List<String> inheritedPrograms(Object object)
      Returns the LPC program path and transitive inherited program paths for a generated LPC object.

      JVMud exposes this as the backing data for LPMud inherit_list compatibility. Generated bytecode exposes inherited compiler metadata through a synthetic method. The object registry supplies the object's own program path. Host objects and older generated classes that do not expose the method are treated as having no LPC inherits rather than failing runtime execution.

    • isDestroyedObject

      public boolean isDestroyedObject(Object object)

    • cloneObject

      public Object cloneObject(String sourcePath)

    • users

      public List<Object> users()
      Returns mudlib-facing interactive personas that are in normal command mode.

      Login controllers waiting for their own input_to() callbacks are still bound to the socket for input delivery, but legacy users() output should not count them as logged-in players. Gameplay objects that are temporarily waiting on another object's input callback, such as a pager command, remain visible.

    • isInteractive

      public boolean isInteractive(Object user)
      Returns true when the supplied LPC object is currently bound to an active JVMud session.

    • bindPlayerSession

      public void bindPlayerSession(String sessionId, String remoteAddress, Consumer<String> sessionOutputSink)

    • bindSession

      public void bindSession(String sessionId, Object persona, String remoteAddress, Consumer<String> sessionOutputSink)

    • bindSession

      public void bindSession(String sessionId, Object persona, String remoteAddress, Consumer<String> sessionOutputSink, MudlibProjection mudlibProjection)

    • rebindSessionLpcObject

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

      The network session, output sink, Player record, and connection metadata stay in place while the mudlib-facing interactive projection changes.

    • bindSessionProtocolSink

      public void bindSessionProtocolSink(Object persona, BiConsumer<String,String> protocolOutputSink)
      Installs the host transport sink used for out-of-band messages to an interactive persona.

    • setSessionProtocolEnabled

      public void setSessionProtocolEnabled(Object persona, String protocol, boolean enabled)
      Records whether a negotiated client protocol is active for an interactive persona.

    • isSessionProtocolEnabled

      public boolean isSessionProtocolEnabled(Object persona, String protocol)
      Returns whether a client protocol has been negotiated for an interactive persona.

    • sendSessionProtocolMessage

      public boolean sendSessionProtocolMessage(Object persona, String protocol, String message)
      Sends one already encoded out-of-band message through a negotiated client protocol.

    • unbindSession

      public void unbindSession(String sessionId)

    • sessionRecord

      public Optional<SessionRecord> sessionRecord(String sessionId)

    • lpcObjectForSession

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

    • playerRecordForSession

      public Optional<PlayerRecord> playerRecordForSession(String sessionId)

    • personaRecordForProjection

      public Optional<PersonaRecord> personaRecordForProjection(Object persona)

    • captureSessionInput

      public void captureSessionInput(String methodName, boolean noEcho, Object... extraArgs)
      Captures the next line of interactive session input for the current output persona.

      The line is delivered to methodName on the current LPC object. Any supplied extra arguments are appended after the typed line, matching legacy input_to() callback shapes such as input_to("method", flags, arg1, arg2).

    • hasCapturedSessionInput

      public boolean hasCapturedSessionInput(Object persona)

    • capturedSessionInputNoEcho

      public boolean capturedSessionInputNoEcho(Object persona)

    • deliverCapturedSessionInput

      public Object deliverCapturedSessionInput(Object persona, String line)
      Delivers one line to a pending input_to() callback while preserving that pending state for runtime queries made during the callback.

    • queryIdle

      public int queryIdle(Object persona)

    • queryIpNumber

      public Object queryIpNumber(Object persona)

    • readMudlibText

      public Object readMudlibText(String path)

    • readMudlibJson

      public Object readMudlibJson(String path)
      Parses an ordinary JSON file rooted inside the mudlib.
      Parameters:
      path - mudlib-relative JSON or gzip-compressed JSON path
      Returns:
      LPC-compatible JSON value, or LPC false when unavailable

    • readMudlibJsonArray

      public Object readMudlibJsonArray(String path, String pointer, int offset, int count)
      Reads a bounded slice from a JSON array inside a mudlib-rooted file.
      Parameters:
      path - mudlib-relative JSON file path
      pointer - RFC 6901 JSON Pointer selecting an array
      offset - zero-based first array entry to return
      count - maximum number of entries to return
      Returns:
      LPC-compatible array slice, or LPC false when the reader cannot access the file

    • listMudlibPaths

      public Object listMudlibPaths(String path, int flags)
      Lists mudlib-rooted paths using an LP-style flag word.

    • appendMudlibText

      public int appendMudlibText(String path, Object text)

    • removeMudlibText

      public int removeMudlibText(String path)

    • copyMudlibText

      public int copyMudlibText(String source, String destination)

    • renameMudlibText

      public int renameMudlibText(String source, String destination)

    • createMudlibDirectory

      public int createMudlibDirectory(String path)

    • removeMudlibDirectory

      public int removeMudlibDirectory(String path)

    • transferCurrentPlayerToGame

      public int transferCurrentPlayerToGame(String gameId)

    • dbConnect

      public int dbConnect(String databaseName)
      Opens a configured JDBC database connection and returns a JVMud database handle.

    • dbConnect

      public int dbConnect(String databaseName, String user, String password)
      Opens a JDBC database connection with mudlib-supplied credentials.

    • dbExec

      public int dbExec(int handle, String sql)
      Executes SQL for a JVMud database handle and returns the handle on success.

    • dbFetch

      public Object dbFetch(int handle)
      Fetches one row from a JVMud database handle's current result cursor.

    • dbError

      public Object dbError(int handle)
      Returns the last JDBC error for a JVMud database handle, or LPC false when clear.

    • dbClose

      public int dbClose(int handle)
      Closes a JVMud database handle.

    • dbHandles

      public List<Integer> dbHandles()
      Returns the currently open JVMud database handles.

    • dbEscape

      public String dbEscape(String value)
      Escapes a string for interpolation into mudlib-generated SQL.

    • saveCurrentLPCObjectState

      public int saveCurrentLPCObjectState(String path)

    • restoreCurrentLPCObjectState

      public int restoreCurrentLPCObjectState(String path)

    • touchPersona

      public void touchPersona(Object persona)

    • invokeObject

      public Object invokeObject(Object target, String methodName, Object... args)

    • invokeOptionalObject

      public Object invokeOptionalObject(Object target, String methodName, Object... args)

    • hasObjectMethod

      public boolean hasObjectMethod(Object target, String methodName, int arity)
      Reports whether a generated LPC object exposes a public method with the requested arity.

      Runtime callable values use this to decide whether a quoted function reference names a method on its lexical object or should fall through to a global efun alias.

      Parameters:
      target - generated LPC object to inspect
      methodName - LPC method name
      arity - number of arguments expected by the caller
      Returns:
      true when the object can receive that method call

    • moveObject

      public void moveObject(Object object, Object destination)
      Moves one LPC object and immediately starts the destination interaction scope for a connected command actor.

      Movement is itself a lifecycle boundary. A room and the nearby objects must observe a connected actor's arrival before that actor can issue another command; deferring their lifecycle methods until the next command can let the actor leave before entrance events and temporary interactions are installed.

    • environment

      public Object environment(Object object)

    • present

      public Object present(Object identifier, Object container)

    • bindEntityAlias

      public void bindEntityAlias(Object object, Object namespace, Object alias)

    • findEntityAlias

      public Object findEntityAlias(Object namespace, Object alias)

    • entityHasAlias

      public int entityHasAlias(Object object, Object namespace)

    • enableEntityCommands

      public void enableEntityCommands(Object object)

    • disableEntityCommands

      public void disableEntityCommands(Object object)

    • entityCommandsEnabled

      public int entityCommandsEnabled(Object object)

    • setEntityTranslucent

      public void setEntityTranslucent(Object object, boolean translucent)

    • entityTranslucent

      public boolean entityTranslucent(Object object)

    • firstInventory

      public Object firstInventory(Object container)

    • nextInventory

      public Object nextInventory(Object object)

    • destructObject

      public void destructObject(Object object)

    • scheduleDeferredCallback

      public void scheduleDeferredCallback(String methodName, int delaySeconds, Object... args)
      Schedules a one-shot callback on the current object without replacing other callbacks that happen to target the same method.

      Method names are not task identities: mudlibs commonly fan out an event by scheduling the same delivery method once per subscriber. Each registration therefore remains independently cancellable and deliverable. The active command actor is also captured per registration so delayed work observes the same actor that initiated it.

    • cancelDeferredCallback

      public int cancelDeferredCallback(String methodName)
      Cancels the earliest pending callback for the named method on the current object.

    • scheduleRecurringTick

      public void scheduleRecurringTick(int enabled, int intervalSeconds)

    • currentObject

      public Object currentObject()

    • previousObject

      public Object previousObject()

    • currentCommandActor

      public Object currentCommandActor()

    • currentCommandVerb

      public String currentCommandVerb()

    • configureCommandAliases

      public void configureCommandAliases(Object aliases)
      Installs host-level command aliases used before LPC action lookup.

      Compatibility mudlibs may configure a command-modification hook with mappings such as ([ "n": "north" ]). JVMud keeps that compatibility at the runtime command boundary: the first word is rewritten before registered add_action verbs are selected, and query_verb() sees the expanded verb.

    • notifyCommandFailure

      public int notifyCommandFailure(Object message)
      Records the command failure text to display when no command action accepts the line.

      Legacy mudlibs use notify_fail() inside an action that returns false. JVMud stores the latest message for the active dispatch and writes it only after all candidate actions have declined the command.

    • pushCurrentObject

      public void pushCurrentObject(Object object)

    • popCurrentObject

      public void popCurrentObject()

    • withCurrentObject

      public <T> T withCurrentObject(Object object, Supplier<T> action)

    • runWithCurrentObject

      public void runWithCurrentObject(Object object, Runnable action)

    • withCommandActor

      public <T> T withCommandActor(Object actor, Supplier<T> action)

    • rememberActionMethod

      public void rememberActionMethod(String methodName)

    • registerVerb

      public void registerVerb(String verb)

    • registerVerb

      public void registerVerb(String verb, boolean prefixMatch)
      Registers a pending LPC command action for the active command actor.

      Agent-owned actions may be declared while an LPC object is initializing, before any command is being dispatched. In that persistent case, the action is bound to the current LPC object itself so it remains available after initialization. Scoped interaction registrations, such as location-specific init() actions, still require the command actor supplied by the refresh pass.

    • clearCommandActions

      public void clearCommandActions(Object actor)

    • removeCommandActions

      public int removeCommandActions(Object actor, Object handler)
      Removes command actions owned by a handler from one actor's current command table.

      This backs compatibility remove_action() calls used by temporary selectors and conversations. The mudlib names the actor whose command table should be edited; JVMud uses the current LPC object as the owning action handler.

    • clearPendingActionMethods

      public void clearPendingActionMethods()

    • withScopedCommandRegistration

      public <T> T withScopedCommandRegistration(Supplier<T> action)

    • dispatchCommand

      public Object dispatchCommand(Object actor, String commandLine)

    • setLight

      public int setLight(int delta)