JVMud

JVMud is an experimental LPC/LPMud text-world engine for the JVM. The project is organized around compiler, engine, instance, transport, persistence, and mudlib responsibilities. JVMud-owned Java code lives under the conventional Maven src/ tree, while third-party and authored mudlibs live under mudlibs/.

docs/PRINCIPLES.md is the controlling design document for the engine, and docs/GLOSSARY.md defines JVMud vocabulary. The engine is being built around JVMud's core concepts: Game, Text, Multiplayer, Interactive, World (Linked Places, Entities, Movement), Persistence, Temporality, and Presence. JVMud has a sole LPC/LPMud target: compatibility choices should deepen that target, not broaden the engine into a generic MUD framework. The upstream mudlib should remain unchanged by default; compatibility belongs in dedicated mudlib-side shim objects plus the engine/compiler support needed to host them.

Here "LPMud" means LPC-authored game worlds compiled into live objects that can be rewritten, recompiled, and reloaded without rebooting the whole game. It does not mean JVMud adopts legacy driver concepts such as rooms, heartbeats, applies, call_outs, or master objects as engine ontology.

Repository Layout

Path	Purpose
src/main/java/io/github/protasm/jvmud/engine/	JVMud engine source. It contains subpackages for world ontology, player/session/persona identity, time, mudlib boundaries, output formatting, and small shared support helpers.
src/main/java/io/github/protasm/jvmud/compiler/	JVMud compiler Java source. It contains the LPC preprocessor, scanner, parser, semantic analysis, IR, bytecode compiler, efun contracts/catalogs, generated-code runtime helpers, and host-facing LPC loader classes.
src/main/java/io/github/protasm/jvmud/instance/	JVMud hosted-instance source. It boots a mudlib, assembles compiler output with engine runtime state, attaches Personas, and manages a running world.
src/main/java/io/github/protasm/jvmud/transport/	JVMud player-transport source. It owns Telnet sockets, sessions, protocol echo behavior, line I/O, and connection lifecycle mechanics.
src/main/java/io/github/protasm/jvmud/persistence/	JVMud persistence adapters for durable filesystem and JDBC-backed state.
src/main/java/io/github/protasm/jvmud/cli/	JVMud local admin CLI source. It is a single-user command-line tool for filesystem navigation, object loading, inspection, invocation, and mutation.
src/test/java/io/github/protasm/jvmud/	JVMud Java test source, following the same package layout.
mudlibs/lpmuseum/	Native JVMud mudlib content. This is the free-standing Telnet landing experience and museum concourse for exhibit mudlibs.
mudlibs/lp245/	Vanilla LPMUD 2.4.5 exhibit mudlib content. Treat upstream files as read-only unless an explicit style or formatting change is requested; add compatibility through dedicated independent shim objects.
docs/	Static project site published from simple HTML.

Runtime Status

The engine-owned model lives under io.github.protasm.jvmud.engine:

• engine.world: World, WorldRuntime, Place, Entity, Link, Location, and Capability
• engine.identity: Player, Session, and Persona ids and record types
• engine.time: WorldScheduler, ScheduledTask, and WorldClock
• engine.mudlib: MudlibBoundary, lifecycle events, and mudlib projections
• engine.output: text presentation helpers for output leaving the runtime
• engine.support: small shared model helpers that do not define engine ontology

WorldRuntime owns single containment: every Entity has one immediate Location, movement updates the containment graph, and containment cycles are rejected. It also owns navigable links between places, so the engine models a world as connected containment rather than only an assemblage of isolated places. Links are strictly place-to-place; entities can be contained by places or other entities, but entities are not link endpoints.

Compiler Status

The compiler source is present at:

src/main/java/io/github/protasm/jvmud/compiler/

The compiler is now under the JVMud umbrella package, io.github.protasm.jvmud.compiler.

Important compiler packages include:

• preproc: include resolution, macro expansion, conditional directives, and source mapping.
• scanner and token: lexical analysis and token model.
• parser: Pratt parser, parselets, AST nodes, and LPC type/operator models.
• semantic and ir: semantic analysis, type checking, and typed intermediate representation.
• bytecode: JVM bytecode generation using ASM.
• efun: LPC-facing efun contracts plus the built-in efun.builtin.CoreEfuns catalog.
• runtime: compiled-LPC support helpers used by generated bytecode, not the engine ontology.
• exec: host-facing LPC class loading and object execution APIs.
• pipeline: orchestration for preprocessing, scanning, parsing, semantic analysis, IR lowering, and bytecode generation.

io.github.protasm.jvmud.compiler.JVMudCompiler is the current facade and command-line entry point. It compiles one LPC source file to a JVM class file when invoked with:

JVMudCompiler <source-file> [output-dir]

Build Notes

The repository uses the conventional single-project Maven layout. Run the current baseline with:

mvn test

The project depends on ASM for bytecode generation and JUnit Jupiter for tests. The current test suite includes end-to-end compiler/runtime smoke tests and an informational mudlib compatibility scan. The scan writes:

target/jvmud-mudlib-compatibility.md

That report is deliberately non-failing: it records current parser, semantic, function, and runtime gaps while keeping the green build useful.

See docs/GLOSSARY.md for JVMud terminology. See docs/ROADMAP.md for the full-stack project waypoints. See docs/ENGINE_MUDLIB_CONTRACT.md for the native JVMud boundary between the engine and mudlib compatibility layer.

Engine-First Development

Development should start from docs/PRINCIPLES.md, then make compiler, runtime, CLI, and compatibility choices fit that model. The mudlib is content for JVMud, not a constraint that forces the engine to recreate every legacy legacy LPC engine behavior. At the same time, the vanilla mudlib source is upstream material and should not be rewritten merely to compensate for JVMud gaps.

When a conflict appears, prefer:

• engine semantics that clearly model world, place, entity, location, containment, presence, perception, persistence, and time;
• compiler and runtime support for the sole LPC/LPMud target rather than alternate mudlib languages or generic MUD abstractions;
• live object reload semantics for LPC-authored game code without turning legacy LPMud driver vocabulary into JVMud engine concepts;
• compiler/runtime support that can host legacy LPC content without distorting the JVMud ontology;
• dedicated mudlib-side compatibility shims, such as mfun objects, shadow, or adapter objects, instead of broad edits to upstream mudlib files;
• JVMud-native engine operation names, with legacy LPC method and engine function names translated by compatibility shims;
• small bridge APIs only where they keep current LPC content usable.

Admin CLI And Telnet Transport

The cli module provides a local, single-user admin shell backed by the real object runtime. After building, run it with:

scripts/jvmud-admin

The launcher compiles the project, then starts the shell with the local build output. Optionally pass a mudlib config file as the single argument.

The shell is admin-only: every input line is parsed as an admin command. Commands include boot, call, cat, cd, clone, destruct, inspect, load, look, ls, move, objects, pwd, reload, verbosity, where, and quit. Some commands have single-character shortcuts; run help in the shell to see the current alias list and per-command usage notes.

The CLI includes a mudlib-rooted virtual filesystem. If the config file is /Users/jonathan/Projects/jvmud/mudlibs/lpmuseum/jvmud/lpmuseum.config, then CLI path / maps to /Users/jonathan/Projects/jvmud/mudlibs/lpmuseum. Filesystem commands cannot navigate above the mudlib root.

Use verbosity quiet, verbosity normal, or verbosity watch to control shell output. watch prints compiler stage progress for commands such as load and clone, which is useful when inspecting parser, analyzer, lowering, or bytecode failures.

The instance package provides the player-facing hosted world, while transport.telnet provides the Telnet path into that world. Start a mudlib as a persistent Telnet target with:

scripts/jvmud-start [mudlib-config-file]

The config argument is optional. By default it serves native JVMud LPMuseum from mudlibs/lpmuseum/jvmud/lpmuseum.config on localhost:4000. Telnet connections arrive in the LPMuseum concourse through the museum's own Persona object, command grammar, Places, and Entities. LPMuseum includes stub portal mount points for future exhibit mudlibs, but it does not need any exhibit content to boot or play. To boot LP245 directly for compatibility testing, pass mudlibs/lp245/jvmud/lp245.config.

Player/world input is routed through LPC init, add_action, and add_verb registrations on nearby or carried objects. Telnet slash commands are limited to session controls such as /help and /quit; admin inspection and object mutation stay in the admin CLI. This is still an early development listener: session-to-session messaging, output isolation between participants, and production networking policy belong to later instance and transport slices.

To run the startup smoke test that launches jvmud-start, connects over TCP, verifies that the configured obj/player mudlib player object attaches, drives the vanilla login prompts through captured input, and checks look plus movement from the church to the village green and humpbacked bridge:

scripts/smoke-jvmud-start.sh

Development Notes

• Keep changes scoped to the relevant package under src/main/java/io/github/protasm/jvmud/, mudlibs/lp245/, or docs/.
• Use docs/PRINCIPLES.md as the source of truth for engine concepts. Do not edit vanilla mudlib files unless explicitly asked for style or formatting changes; prefer dedicated compatibility shim objects and engine/compiler support.
• Treat io.github.protasm.jvmud.engine and mudlibs/lp245/ as intentionally separate from compiler internals: compiler helpers used by generated bytecode currently remain under src/main/java/io/github/protasm/jvmud/compiler/runtime/.
• Keep untyped LPC methods and untyped method parameters as compiler errors. Mudlib compatibility work should add explicit LPC signatures to mudlib source files rather than relaxing semantic analysis.
• Prioritize readability alongside functionality. Prefer clear names, focused tests, and short comments explaining non-obvious legacy LPC engine semantics or bytecode/runtime lifecycle rules.