openRoads 🌍

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 - How to install and set up openRoads

• Configuration Guide - Complete configuration including server tick system, spawning, and performance tuning

• Display System - UI/TUI features including room display, input handling, and partial matching

• Architecture Overview - Understanding how openRoads works

• Development Guide - Contributing to or modifying openRoads

• API Documentation - Internal API reference for developers

• Enemy Spawning System - How the automatic enemy spawning works

✨ Spell System Documentation

• Spell System Overview - Complete spell system architecture and features

• Spell Creation Quick Start - Get started creating spells in 5 minutes

• YAML Spell Tutorial - Step-by-step guide for creating YAML spells

• JSON Spell Guide - Working with hardcoded JSON spells

• Spell Effects Reference - Complete reference for all spell effects

• Custom Spells Directory - 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.

---

⚒️ 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.

---

🧪 Testing

To run the comprehensive functionality demo:

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:

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

• complete base player save logic

• complete base player movement

• add comprehensive documentation

• implement server tick system with configurable timing

• enforce max instances for enemy spawning

• enhance input handling with backspace support

• implement partial matching for look commands

• consolidate documentation into organized structure

• complete combat system with weapons and armor

• implement equipment management (arm/disarm/wear/disrobe)

• add speed-based combat timing for PvP

• implement player vs player combat with cooldowns

• create starting equipment for new players

• implement unarmed combat with damage penalties

• differentiate PvE (no cooldown) vs PvP (cooldown) combat

• add enemy retaliation system (60% chance)

• implement go routine-based enemy retaliation processing

• add asynchronous retaliation with natural timing delays

• implement element-based respawn system

• add automatic room management for player death/respawn

• implement comprehensive spell casting system

• create YAML-based spell configuration system

• add individual spell files in spells/custom/ directory

• implement spell effects (damage, heal, summon, teleport, stat mod)

• add spell cooldowns, cast times, and restrictions

• 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.