# openRoads 🌍

## [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://gitlab.phospher.com/darkhorse7881/openroads/-/blob/main/docs/LICENSE/README.md)[![Built for Synchronet](https://img.shields.io/badge/BBS-Synchronet-orange)](https://www.synchro.net/)[![Golang](https://img.shields.io/badge/Language-Golang-yellow.svg)](https://go.dev/)[![MUD-style](https://img.shields.io/badge/Game-Type%3A%20MUD-lightgrey)](https://docs.openroads.dev/readme)[![Status: In Development](https://img.shields.io/badge/Status-In--Progress-yellow)](https://docs.openroads.dev/readme)[![Latest Release](https://gitlab.phospher.com/darkhorse7881/openroads/-/badges/release.svg)](https://gitlab.phospher.com/darkhorse7881/openroads/-/releases)[![Join our Discord](https://img.shields.io/badge/join%20our-Discord-%235865F2.svg)](https://discord.gg/42zvWQRhnS)

**openRoads** is a retro-style, multiplayer, room-based RPG rewrote for the Synchronet BBS system. players can explore a shared world, chat, encounter random events, and more — all from a terminal.

> Think *Crossroads of the Elements* meets modern BBS scripting.

***

## ✨ Features

* 🌐 **Multiplayer**: All players share the same world in real-time.
* 🗺️ **Room System**: Rooms are modular and fully customizable.
* 🌠 **Random Room Events**: Dynamic, room-specific events that all players in a room experience together.
* 🧠 **Asynchronous Game Logic**: Handled with background routines for realism.
* 👹 **Intelligent Enemy Spawning**: Enemies spawn automatically based on room ranges, timing constraints, and max instances.
* ⏱️ **Server Tick System**: Configurable tick-based timing for precise spawn control and performance tuning.
* 📦 **Smart Item & Enemy Display**: Items and enemies in rooms are displayed with proper grammar and formatting.
* 👁️ **Enhanced Look Command**: Look at specific items, enemies, and players for detailed descriptions. Works in brief mode.
* ⚔️ **Combat System**: Full combat mechanics with weapons, armor, unarmed combat, and differentiated PvE/PvP timing.
* 🛡️ **Equipment System**: Arm weapons and wear armor with realistic restrictions and stat bonuses.
* 🎯 **Tactical Combat**: PvE allows rapid attacks, PvP uses speed-based cooldowns to prevent spam.
* 👹 **Enemy Retaliation**: Go routine-based enemy retaliation system with 60% chance, natural timing delays.
* 🏠 **Element-Based Respawn**: Players respawn in their element room (Earth→3, Air→4, Fire→5, Water→6) with full HP.
* ✨ **Spell System**: Comprehensive YAML/JSON-based spell system with individual spell files, effects, cooldowns, and cast times.
* 🔮 **Magic Effects**: Damage, healing, summoning, teleportation, stat modification, and custom spell effects.
* 📝 **Easy Spell Creation**: Create new spells without coding using YAML files in `spells/custom/` directory.
* 🖥️ **Built in Golang** for Synchronet.
* 💾 **Lightweight** and runs entirely inside your BBS.

***

## 📚 Documentation

### 🎯 Core System Documentation

* [Installation Guide](https://docs.openroads.dev/installation) - How to install and set up openRoads
* [Configuration Guide](https://docs.openroads.dev/configuration) - Complete configuration including server tick system, spawning, and performance tuning
* [Display System](https://docs.openroads.dev/display) - UI/TUI features including room display, input handling, and partial matching
* [Architecture Overview](https://docs.openroads.dev/architecture) - Understanding how openRoads works
* [Development Guide](https://docs.openroads.dev/development) - Contributing to or modifying openRoads
* [API Documentation](https://docs.openroads.dev/api) - Internal API reference for developers
* [Enemy Spawning System](https://docs.openroads.dev/enemy_spawning) - How the automatic enemy spawning works

### ✨ Spell System Documentation

* [Spell System Overview](https://docs.openroads.dev/spell_system) - Complete spell system architecture and features
* [Spell Creation Quick Start](https://docs.openroads.dev/spell_creation_quickstart) - Get started creating spells in 5 minutes
* [YAML Spell Tutorial](https://docs.openroads.dev/yaml_spell_tutorial) - Step-by-step guide for creating YAML spells
* [JSON Spell Guide](https://docs.openroads.dev/json_spell_guide) - Working with hardcoded JSON spells
* [Spell Effects Reference](https://docs.openroads.dev/spell_effects_reference) - Complete reference for all spell effects
* [Custom Spells Directory](https://gitlab.phospher.com/darkhorse7881/openroads/-/blob/main/spells/custom/README.md) - Individual spell files guide and examples

***

## 📁 File Structure

```
openroads/
├── config
│   ├── config.go
│   └── config.ini
├── dev_tools
│   ├── createRelease.sh
│   └── saveToGit.sh
├── docs
│   ├── api.md
│   ├── architecture.md
│   ├── configuration.md
│   ├── development.md
│   └── installation.md
├── go.mod
├── lib
│   ├── enemies.go
│   ├── player.go
│   ├── ui.go
│   └── world.go
├── LICENSE
├── openroads
├── README.md
├── routines
│   ├── cleanup.go
│   ├── engine.go
│   └── spawning.go
├── server.go
├── world
│   ├── enemies.json
│   ├── formatted_rooms.json
│   └── players.json
└── xroads.go
```

***

## 🚀 Getting Started

1. **Install Synchronet** if you haven't already.
2. Clone or download this repo to your `sbbs/xtrn/` folder.
3. run the prebuilt binary (./openroads)
4. connect to the game: `?rlogin 127.0.0.1:2025 -q -c`

For detailed installation instructions, see the [Installation Guide](https://gitlab.phospher.com/darkhorse7881/openroads/-/blob/main/docs/docs/installation.md).

***

## ⚒️ Configuration

All room and player data files are stored in `world/`. You can easily add more rooms in the JSON file or code.

For detailed configuration options, see the [Configuration Guide](https://gitlab.phospher.com/darkhorse7881/openroads/-/blob/main/docs/docs/configuration.md).

***

## 🧪 Testing

To run the comprehensive functionality demo:

```bash
go run tests/comprehensive_demo.go
```

This demo tests and demonstrates:

* Configuration system loading
* Server tick system and max instances enforcement
* Enemy spawning mechanics
* Display system formatting
* Input handling and backspace support
* Partial matching for look commands
* Combat system mechanics and equipment

For unit tests:

```bash
go test ./...
```

***

## 📝 To Do

* [ ] complete npc logic
* [ ] expand weapon and armor catalog
* [ ] implement consumable items (potions, food)
* [ ] implement player guilds/parties
* [ ] add spell scripting with Lua support
* [ ] implement spell hot-reloading

## ✅ Completed

* [x] complete base player save logic
* [x] complete base player movement
* [x] add comprehensive documentation
* [x] implement server tick system with configurable timing
* [x] enforce max instances for enemy spawning
* [x] enhance input handling with backspace support
* [x] implement partial matching for look commands
* [x] consolidate documentation into organized structure
* [x] complete combat system with weapons and armor
* [x] implement equipment management (arm/disarm/wear/disrobe)
* [x] add speed-based combat timing for PvP
* [x] implement player vs player combat with cooldowns
* [x] create starting equipment for new players
* [x] implement unarmed combat with damage penalties
* [x] differentiate PvE (no cooldown) vs PvP (cooldown) combat
* [x] add enemy retaliation system (60% chance)
* [x] implement go routine-based enemy retaliation processing
* [x] add asynchronous retaliation with natural timing delays
* [x] implement element-based respawn system
* [x] add automatic room management for player death/respawn
* [x] implement comprehensive spell casting system
* [x] create YAML-based spell configuration system
* [x] add individual spell files in spells/custom/ directory
* [x] implement spell effects (damage, heal, summon, teleport, stat mod)
* [x] add spell cooldowns, cast times, and restrictions
* [x] create spell validation and requirement checking

***

## 🧠 Credits

* Mason Scott Coloretti (main dev)
* Brian Scott Miller (Sysop of bbs.phospher.com)
* Desean (for parser scripts for the game and feedback)
* Synchronet community
* BBS fans everywhere keeping the scene alive

***

## 📜 License

MIT — do what you want, just don’t sue 😄

***

🌀 *BBS gaming ain't dead — it's just been waiting for a reboot.*


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.openroads.dev/readme.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.