Class CoreEfuns

java.lang.Object
io.github.protasm.jvmud.compiler.efun.builtin.CoreEfuns
public final class CoreEfuns extends Object
Defines and registers JVMud's built-in LPC-facing engine functions.

These functions are the lowest-level operations that compiled mudlib code can ask the JVMud engine to perform. They intentionally use JVMud engine vocabulary: Entity identity, location containment, command dispatch, session input capture, scheduler callbacks, and perceivable output. Legacy LP driver names belong in mudlib-side compatibility objects, where they can delegate to these engine operations without turning LPC compatibility terms into the engine's own model.

Most users should treat this class as the authoritative catalog of core efuns. Each entry created by the internal catalog builder has a name, LPC return type, LPC parameter types, and a Java implementation that receives the active RuntimeContext. The same catalog can be installed into a raw generated-code context with registerCore(RuntimeContext) or into a host-facing LPCRuntime with registerCore(LPCRuntime).

Output and perception

  • jvmud_write(mixed message) : void writes text to the current execution recipient.
  • jvmud_write_to_lpc_object(object target, mixed message) : void writes text to the target object's bound session, when it has one.
  • jvmud_rebind_session_lpc_object(object newObject, object oldObject) : status moves an interactive session binding from one LPC object to another.
  • jvmud_emit_perceivable(mixed emitter, mixed message) : void emits near an entity or path-resolved object.
  • jvmud_emit_perceivable_except(mixed emitter, mixed message, mixed excluded) : void emits near an entity while suppressing one recipient.
  • jvmud_emit_perceivable_at(mixed location, mixed message) : void emits at a location or path-resolved object.

Current execution context

  • jvmud_current_lpc_object() : object returns the currently executing LPC object.
  • jvmud_previous_lpc_object() : object returns the previous LPC object in the current call chain, where one is available.
  • jvmud_current_actor() : object returns the active command actor, falling back to the current object outside command dispatch.
  • jvmud_current_agent() : object returns the active world-present agent responsible for the current action scope, or LPC false when no agent is active.
  • jvmud_current_verb() : string returns the verb being dispatched for the current command.
  • jvmud_set_driver_hook(int hook, mixed callback) : void stores supported compatibility driver hooks such as command alias rewrites.
  • jvmud_notify_fail(mixed message) : int records failure text for an unhandled command.

Command dispatch and interactions

  • jvmud_dispatch_entity_command(mixed actor, string commandLine) : mixed dispatches a command as an entity or path-resolved object.
  • jvmud_enable_commands() : void enables command handling for the current object.
  • jvmud_add_action(string methodName) : void remembers a method as a command action without registering a verb.
  • jvmud_add_action(string methodName, string verb) : void remembers an action method and registers a verb.
  • jvmud_add_action(string methodName, string verb, status prefix) : void registers a verb, optionally as a prefix verb.
  • jvmud_remove_action(int flags) : int removes current handler actions from the active command actor.
  • jvmud_remove_action(int flags, mixed actor) : int removes current handler actions from the supplied actor.
  • jvmud_add_verb(string verb) : void registers a verb for the current interaction scope.

Time, scheduling, and randomness

  • jvmud_time() : int returns Unix epoch seconds.
  • jvmud_format_time(int epochSeconds) : string formats epoch seconds using the host's default time zone.
  • jvmud_random(int max) : int returns a value in [0, max), or 0 when max <= 0.
  • jvmud_schedule_recurring_tick(int enabled, int intervalSeconds) : void schedules or disables recurring ticks for the current object.
  • jvmud_schedule_deferred_callback(string methodName, int delaySeconds) : void schedules a one-shot callback on the current object.
  • jvmud_schedule_deferred_callback(string methodName, int delaySeconds, mixed... args) : void schedules a one-shot callback with mudlib-supplied arguments.
  • jvmud_cancel_deferred_callback(string methodName) : int cancels matching deferred callbacks and returns the runtime's cancellation count/status.

LPC object identity plus entity lookup, containment, and lifecycle

  • jvmud_lpc_object_id(mixed object) : string returns the runtime object identifier for a loaded LPC object.
  • jvmud_method_exists(string name) : status returns whether the current LPC object exposes a public mudlib method with that name.
  • jvmud_method_exists(string name, mixed object) : status checks another loaded LPC object for a public mudlib method.
  • jvmud_lpc_object_methods(mixed object) : array returns the public mudlib method names exposed by a loaded LPC object.
  • jvmud_inherited_programs(mixed object) : array returns the transitive LPC program paths inherited by a generated object.
  • jvmud_load_lpc_object(string path) : object loads or returns the shared LPC runtime object for a mudlib path.
  • jvmud_clone_lpc_object(string path) : object clones an LPC object and returns the new runtime instance.
  • jvmud_set_entity_location(mixed entity, mixed location) : void sets a world-present entity's runtime location/containment without using a mudlib movement wrapper.
  • jvmud_move_entity(mixed entity, mixed destination) : void moves an entity or path-resolved object.
  • jvmud_find_entity(string id) : object searches for an entity in the default location scope.
  • jvmud_find_entity(mixed id, mixed location) : object searches for an entity inside a location or container.
  • jvmud_entity_location() : object returns the current object's location.
  • jvmud_entity_location(mixed entity) : object returns another entity's location.
  • jvmud_first_entity_at(mixed location) : object returns the first entity in a location or container.
  • jvmud_next_entity_at(mixed entity) : object returns the next entity in the same inventory walk.
  • jvmud_destroy_lpc_object(object object) : void destroys an LPC object and removes its runtime state.

Aliases and command capability

  • jvmud_bind_entity_alias(object entity, string alias, mixed location) : void binds a lookup alias in a location scope.
  • jvmud_find_entity_alias(string alias, mixed location) : object resolves an alias in a location scope.
  • jvmud_entity_has_alias(mixed entity, string alias) : status reports whether an entity has an alias.
  • jvmud_entity_commands_enabled(mixed entity) : status reports whether command handling is enabled for an entity.
  • jvmud_set_entity_translucent(mixed entity, status translucent) : void controls whether ambient perception such as light passes through an entity container. Entities are translucent by default.
  • jvmud_entity_translucent(mixed entity) : status reports whether an entity is currently translucent.

Session, users, persistence, and security helpers

  • jvmud_users() : array returns the active user/player objects known to the runtime.
  • jvmud_find_player(string name) : object finds an active interactive user/player by common mudlib name methods.
  • jvmud_previous_object() : object returns the previous LPC object on the runtime call stack.
  • jvmud_interactive(mixed user) : status reports whether an object is bound to an active session.
  • jvmud_interactive_info(mixed user, int key) : mixed returns LPC false for driver-specific interactive metadata JVMud does not expose.
  • jvmud_lpc_object_info(mixed object, int key) : mixed returns LPC false for driver-specific object metadata JVMud does not expose.
  • jvmud_configure_lpc_object(mixed object, int key, mixed value) : status bridges supported driver object configuration requests such as command enablement.
  • jvmud_find_lpc_object(string path) : mixed returns an already loaded LPC object, or LPC false when the path is not loaded.
  • jvmud_to_lpc_object(mixed pathOrObject) : mixed resolves an LPC object value or returns LPC false when no loaded object matches.
  • jvmud_shutdown() : void accepts legacy mudlib shutdown requests.
  • jvmud_set_this_player(mixed player) : void accepts legacy current-player mutation requests while JVMud keeps session ownership on the engine side.
  • jvmud_raise_error(mixed message) : void raises a JVMud runtime exception with the supplied LPC message.
  • jvmud_query_idle(mixed user) : int returns idle time for a user/player object.
  • jvmud_query_ip_number(mixed user) : mixed returns the user's remote IP address, or the runtime's false/null value when unavailable.
  • jvmud_query_ip_name(mixed user) : mixed returns the user's remote host address, or the runtime's false/null value when unavailable.
  • jvmud_driver_info(int key) : mixed returns LPC false for unsupported driver-info queries.
  • jvmud_capture_session_input(string methodName, int flags[, mixed ...args]) : void routes the next session input line to a method on the current object, followed by any captured compatibility arguments.
  • jvmud_transfer_player_to_game(string gameId) : status asks the host to transfer the current player to another registered game.
  • jvmud_save_lpc_object_state(string path) : status persists the current object's LPC fields.
  • jvmud_restore_lpc_object_state(string path) : status restores the current object's LPC fields.
  • jvmud_db_connect(string database) : int opens a configured JDBC database handle.
  • jvmud_db_connect(string database, string user, string password) : int opens a JDBC database handle with mudlib-supplied credentials.
  • jvmud_db_exec(int handle, string sql) : int executes SQL and retains any result cursor for later fetches.
  • jvmud_db_fetch(int handle) : mixed returns the next result row as an LPC array, or LPC false when no row remains.
  • jvmud_db_error(int handle) : mixed returns the last SQL error for a handle.
  • jvmud_db_close(int handle) : status closes a database handle.
  • jvmud_db_handles() : array returns currently open database handles.
  • jvmud_db_escape(mixed value) : string escapes text for mudlib-generated SQL.
  • jvmud_hash_password(string password) : string returns a PBKDF2-SHA256 password hash string.
  • jvmud_verify_password(string password, string encodedHash) : status verifies a password against a hash created by jvmud_hash_password.

Text, collections, invocation, and compatibility helpers

  • jvmud_read_mudlib_text(string path[, int startLine, int lineCount]) : mixed reads a mudlib-relative text file, optionally slicing lines for legacy read_file calls.
  • jvmud_list_mudlib_paths(string path[, int flags]) : array lists mudlib-relative file names, including simple glob support for compatibility file discovery.
  • jvmud_append_mudlib_text(string path, mixed text) : status appends text to a mudlib-relative file.
  • jvmud_remove_mudlib_text(string path) : status removes a mudlib-relative file.
  • jvmud_copy_mudlib_text(string source, string destination) : int copies a mudlib-relative file, returning LDMud-style zero for success.
  • jvmud_rename_mudlib_text(string source, string destination) : int renames a mudlib-relative path, returning LDMud-style zero for success.
  • jvmud_create_mudlib_directory(string path) : status creates a mudlib-relative directory.
  • jvmud_remove_mudlib_directory(string path) : status removes an empty mudlib-relative directory.
  • jvmud_size(mixed value) : int returns the size of a string, collection, mapping, or array.
  • jvmud_sqrt(mixed value) : float returns the square root of a numeric value.
  • jvmud_lowercase_text(mixed value) : string lowercases text.
  • jvmud_uppercase_text(mixed value) : string uppercases text.
  • jvmud_split_text(string text, string delimiter) : array splits text on a literal delimiter while preserving empty trailing fields.
  • jvmud_regex_match(array values, string pattern[, int flags]) : mixed returns the values whose string forms match a regular expression, or LPC false when no value matches. JVMud accepts common LDMud regexp idioms before running the pattern on Java's regex engine.
  • jvmud_regex_replace(string input, string pattern, mixed replacement, int flags) : string performs a compatibility regex replacement for legacy mudlib text helpers, including function callbacks that receive each matched string.
  • jvmud_regex_explode(string input, string pattern) : array splits text around regular-expression matches while preserving matched delimiters.
  • jvmud_to_int(mixed value) : int converts numeric values and base-10 text to an integer, returning LPC false-style zero for non-numeric input.
  • jvmud_to_string(mixed value) : string converts a mixed LPC value to its JVMud text form for compatibility helpers that need explicit stringification.
  • jvmud_capitalize_text(mixed value) : string capitalizes the first character of text.
  • jvmud_wrap_text(mixed text[, int width]) : string wraps description text at a requested line width, defaulting to 78 columns for compatibility text helpers.
  • jvmud_serialize_lpc_value(mixed value) : string serializes LPC data values to a JVMud-owned tagged JSON payload.
  • jvmud_deserialize_lpc_value(string data) : mixed restores LPC data values produced by jvmud_serialize_lpc_value.
  • jvmud_format_text(string format, mixed ...args) : string formats text using the host formatter with LPC %O object placeholders treated as string placeholders and LDMud string column mode handled directly; this overload is registered for arities 1 through 24.
  • jvmud_extract_text(mixed value, int from) : string extracts text from an inclusive start index through the end.
  • jvmud_extract_text(mixed value, int from, int to) : string extracts text using inclusive start and end indexes.
  • jvmud_member(mixed value, mixed needle) : int checks mapping key membership or returns the index of a value in an array or string.
  • jvmud_sort_array(array values, mixed comparator[, mixed ...args]) : array sorts a copy of an array using a callable comparator or current-object method name. Mudlib manifests can expose this under legacy names such as sort_array.
  • jvmud_filter(mixed values, function callback, mixed ...args) : mixed filters arrays, strings, and mappings with a callable predicate. Mudlib manifests can expose this under legacy names such as filter.
  • jvmud_map(mixed values, function callback, mixed ...args) : mixed maps arrays, strings, and mappings with a callable transformer. Mudlib manifests can expose this under legacy names such as map.
  • jvmud_mapping_keys(mapping value) : array returns the mapping's keys in runtime iteration order.
  • jvmud_mapping_values(mapping value) : array returns the mapping's values in runtime iteration order.
  • jvmud_mapping_values(mapping value, int index) : array returns one value slot from each entry in an LDMud multi-value mapping.
  • jvmud_mapping_from_keys(array keys) : mapping builds a mapping whose keys come from the supplied array and whose values are LPC true.
  • jvmud_mapping_delete(mapping value, mixed key) : mapping removes a key from a mutable mapping and returns the same mapping.
  • jvmud_is_string(mixed value) : status reports whether a value is Java-backed LPC string data.
  • jvmud_is_int(mixed value) : status reports whether a value is Java-backed LPC integer data.
  • jvmud_is_float(mixed value) : status reports whether a value is Java-backed LPC floating point data.
  • jvmud_is_object(mixed value) : status reports whether a value is a live runtime object.
  • jvmud_is_array(mixed value) : status reports whether a value is Java-backed LPC array data.
  • jvmud_is_mapping(mixed value) : status reports whether a value is Java-backed LPC mapping data.
  • jvmud_filter_indices(mapping values, function callback, mixed ...args) : mapping returns a mapping containing the entries whose keys satisfy a callable predicate; this overload is registered for arities 2 through 8.
  • jvmud_allocate(int size) : array returns a zero-filled LPC array of non-negative size.
  • jvmud_sscanf(mixed input, mixed format, mixed ...captures) : int is registered for arities 3 through 8.
  • jvmud_apply_callable(function callback, mixed ...args) : mixed invokes a callable and expands a final array argument for LDMud-style apply calls.
  • jvmud_invoke_lpc_object(mixed target, string methodName, mixed ...args) : mixed invokes an optional method on an LPC object or path-resolved shared object; this overload is registered for arities 2 through 6.
  • jvmud_set_light(int delta) : int adjusts the current runtime light level and returns the resulting value.

  • Method Details

    • registerCore

      public static void registerCore(RuntimeContext context)
      Registers the complete core efun set directly into a generated-code runtime context.

      Use this when tests or lower-level runtime code already have the RuntimeContext that generated bytecode will use. The supplied context receives fresh Efun instances, including all overloads listed in this class-level catalog.

      Parameters:
      context - runtime context that should resolve built-in efuns
      Throws:
      NullPointerException - if context is null

    • registerCore

      public static void registerCore(LPCRuntime runtime)
      Registers the complete core efun set into a host-facing LPC runtime.

      This is the usual entry point for embedding JVMud through LPCRuntime; the runtime forwards registration to its active RuntimeContext.

      Parameters:
      runtime - host-facing runtime whose generated LPC objects should see the core efuns
      Throws:
      NullPointerException - if runtime is null