# AGENTS.md

This file provides guidance to agentic coding agents when working with code in this repository.

## Project Overview

Read the included "README.md" file for an overview.

## Architecture

### Core Components

**Driver Layer** (`src/`)

- `main.cc` - Entry point for the driver executable
- `backend.cc` - Main game loop and event handling
- `comm.cc` - Network communication layer
- `user.cc` - User/session management
- `symbol.cc` - Symbol table management
- `ofile.cc` - Object file handling

**VM Layer** (`src/vm/`)

- `vm.cc` - Virtual machine initialization and management
- `interpret.cc` - LPC bytecode interpreter
- `simulate.cc` - Simulation engine for object lifecycle
- `master.cc` - Master object management
- `simul_efun.cc` - Simulated external functions

**Compiler Layer** (`src/compiler/`)

- `compiler.cc` - LPC-to-bytecode compiler
- `grammar.y` - Grammar definition (Bison)
- `lex.cc` - Lexical analyzer
- `generate.cc` - Code generation

**Packages** (`src/packages/`)

- Modular functionality organized by feature (async, db, crypto, etc.)
- Each package has `.spec` files defining available functions
- Core packages: core, crypto, db, math, parser, sockets, etc.

**Networking** (`src/net/`)

- `telnet.cc` - Telnet protocol implementation
- `websocket.cc` - WebSocket support for web clients
- `tls.cc` - SSL/TLS encryption support
- `msp.cc` - MUD Sound Protocol support

### Build System

**CMake Configuration** (`CMakeLists.txt`, `src/CMakeLists.txt`)

- CMake 3.22+ required
- C++17 and C11 standards
- Jemalloc for memory management (recommended)
- ICU for UTF-8 support
- OpenSSL for crypto features

**Build Options** (key flags)

- `MARCH_NATIVE=ON` (default) - Optimize for current CPU
- `USE_JEMALLOC=ON` - Use jemalloc memory allocator
- `PACKAGE_*` - Enable/disable specific packages
- `ENABLE_SANITIZER=ON` - Enable address sanitizer for debugging

- `STATIC=ON/OFF` - Static vs dynamic linking, unsupported but offered as a build option for those who want to try. Do not test.

## Build Commands

### Development Build

```bash
# Standard development build
mkdir build && cd build
cmake ..
make -j$(nproc) install

# Debug build with sanitizer
cmake .. -DCMAKE_BUILD_TYPE=Debug -DENABLE_SANITIZER=ON
```

### Production Build

```bash
# Production-ready static build
cmake .. -DCMAKE_BUILD_TYPE=Release -DSTATIC=ON -DMARCH_NATIVE=OFF
make install
```

### Package-Specific Builds

```bash
# Build without database support
cmake .. -DPACKAGE_DB=OFF

# Build with specific packages disabled
cmake .. -DPACKAGE_CRYPTO=OFF -DPACKAGE_COMPRESS=OFF
```

## Testing

### Unit Tests

```bash
# Run all tests (requires GTest)
cd build
make test

# Run specific test executable
./src/lpc_tests
./src/ofile_tests
```

### LPC Tests

```bash
# Run LPC test suite
cd testsuite
../build/bin/driver etc/config.test -ftest
```

### Integration Testing

```bash
# Run driver with test configuration
./build/bin/driver testsuite/etc/config.test
```

## Continuous Integration

There is no CI in LODOS.

## Development Workflow

### Code Standards

Read the ".editorconfig" file for code standards.

### Code Generation

Several source files are auto-generated during build:

- `grammar.autogen.cc/.h` - From `grammar.y` (Bison)
- `efuns.autogen.cc/.h` - From package specifications
- `applies_table.autogen.cc/.h` - From applies definitions
- `options.autogen.h` - From configuration options

### Adding New Functions

1. Add function to appropriate package `.spec` file
2. Implement function in corresponding `.cc` file
3. Run build to regenerate autogenerated files
4. Add tests in `testsuite/` directory

### Debugging

```bash
# Build with debug symbols and sanitizer
cmake .. -DCMAKE_BUILD_TYPE=Debug -DENABLE_SANITIZER=ON

# Run with GDB
gdb --args ./build/bin/driver config.test

# Memory debugging with Valgrind
valgrind --leak-check=full ./build/bin/driver config.test
```

## Key Directories

- `src/` - Main driver source code
- `src/packages/` - Modular package implementations
- `src/vm/` - Virtual machine and interpreter
- `src/compiler/` - LPC compiler
- `src/net/` - Network protocol implementations
- `testsuite/` - LPC test programs and configurations
- `docs/` - Documentation (Markdown and Jekyll)
- `build/` - Build output directory (auto-generated)

## Configuration Files

- `Config.example` - Example driver configuration
- `src/local_options` - Local build options (copy from `local_options.README`)
- `testsuite/etc/config.test` - Test configuration
- Package-specific `.spec` files define available functions

## Common Development Tasks

### Adding a New Package

1. Create directory in `src/packages/[package-name]/`
2. Add `CMakeLists.txt`, `.spec` file, and source files
3. Update `src/packages/CMakeLists.txt`
4. Add tests in `testsuite/`

### Modifying Compiler

1. Edit `src/compiler/grammar.y` for syntax changes
2. Regenerate grammar with Bison if available
3. Update corresponding compiler components

### Modifying Runtime Config Options

Runtime config options (the settings in a driver config file) are defined in
the `INT_FLAGS[]` and `STR_FLAGS[]` tables in `src/base/internal/rc.cc`. These
tables are the single source of truth: the driver parses config files from them,
and `docs/driver/config.md` is generated from their `category`/`description`
fields by `docs/gen_config_docs.py`.

1. Add/change/remove the option's entry in the relevant table in `rc.cc`
   (include a one-line `description` and a `category`)
2. Regenerate the docs: `python3 docs/gen_config_docs.py`
3. Commit `rc.cc` and the regenerated `docs/driver/config.md` together

Options with irregular parsing (ports,
external commands, the global include file, the default fail message) are
hand-documented in the `SPECIAL_OPTIONS` section of `docs/gen_config_docs.py`.

### Debugging Memory Issues

1. Build with `-DENABLE_SANITIZER=ON`
2. Use `mud_status()` efun in LPC for runtime memory info
3. Check `testsuite/log/debug.log` for detailed logs
