# 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.*