From 82840e5df6315528bd7339d50fb88b2cf19a4ed6 Mon Sep 17 00:00:00 2001 From: squid Date: Mon, 12 May 2025 17:20:01 +0200 Subject: [PATCH] docs(README.md): update project name to PrimaUO Server, reorganize and enhance README content with updated project features, scripting system details, available script modules, project structure, configuration instructions, building from source guide, running the server steps, Docker support details, and API documentation information. Remove redundant sections and acknowledgments, and provide a contribution guide. --- README.md | 185 ++++++++++++++++++++++++++++++++++++++---------------- 1 file changed, 130 insertions(+), 55 deletions(-) diff --git a/README.md b/README.md index 0bbeb27..8a0b8d0 100644 --- a/README.md +++ b/README.md @@ -1,90 +1,169 @@ -# Prima - A Modern Ultima Online Server Implementation +# PrimaUO Server +![Docker Image Version (tag)](https://img.shields.io/docker/v/tgiachi/prima-server/latest) +[![GitHub Actions](https://github.com/tgiachi/prima/actions/workflows/docker_image.yml/badge.svg)](https://github.com/tgiachi/prima/actions/workflows/docker_image.yml) +[![License](https://img.shields.io/badge/license-MIT-red.svg)](LICENSE) -![Prima Logo](Assets/prima_logo.png) +![](./Assets/prima_logo.png) -![Build Status](https://img.shields.io/github/workflow/status/tgiachi/prima/CI) +PrimaUO is a modern Ultima Online server implementation written in C# (.NET 9.0). The project aims to provide a modern, extensible, and maintainable server alternative with support for the latest client versions. +## Features -## Overview - -Prima is a modern, high-performance implementation of an Ultima Online server built with C# and .NET 9. This project aims to revive the classic Ultima Online experience while leveraging contemporary software development practices, extensible architecture, and improved performance. - -## Vision +- ⚡ Modern C# (.NET 9.0) implementation +- 🔄 Event-driven architecture +- 🚀 High performance through optimized code and event loop system +- 🔌 Modular design with dependency injection +- 📦 Support for multiple client versions +- 🔒 Secure authentication using JWT +- 📈 Built-in metrics and diagnostics +- 🔧 Extensible through JavaScript scripting system +- 🌐 REST API for integration with external tools + +## Scripting System + +PrimaUO includes a powerful JavaScript scripting engine that allows you to extend and customize server functionality without modifying the core code. Scripts are loaded from the `scripts` directory and can interact with server systems through registered modules. + +### Example Script + +```javascript +// server_startup.js +// This script is executed when the server starts + +// Import script modules +const events = require("events"); +const commands = require("commands"); +const timers = require("timers"); +const scheduler = require("scheduler"); + +// Listen for server started event +events.OnStarted(() => { + console.log("Server has started successfully!"); + + // Register admin commands + commands.RegisterConsoleCommand( + "announce", + "Broadcasts a message to all players", + (args) => { + // Implementation of the announce command + const message = args.join(" "); + console.log(`Broadcasting message: ${message}`); + // Actual broadcast implementation would go here + return true; + }, + ["broadcast", "shout"], + "Console", + "Admin" + ); + + // Create a recurring task to run every 5 minutes + scheduler.ScheduleTask( + "cleanup", + 300, // seconds + () => { + console.log("Running scheduled cleanup task..."); + // Cleanup logic would go here + } + ); + + // Register an event handler for character creation + events.OnCharacterCreated((args) => { + console.log(`New character created: ${args.Name}`); + + // Start a delayed welcome timer + timers.OneShot("welcome_message", 10, () => { + console.log(`Sending welcome message to ${args.Name}`); + // Actual welcome message code would go here + }); + }); +}); +``` -Ultima Online was a groundbreaking MMORPG that pioneered many concepts we take for granted in online gaming today. Prima builds upon this legacy by: +### Available Script Modules -- Reimagining the server architecture with modern design patterns -- Utilizing the latest .NET features for improved performance -- Creating a clean, extensible codebase that's easy to understand and modify -- Supporting both classic and modern UO clients -- Providing robust APIs for custom content creation +- **events**: Subscribe to server events +- **commands**: Register custom commands +- **timers**: Create one-time or repeating timers +- **scheduler**: Schedule tasks to run periodically +- **template**: Add variables for template rendering +- **files**: Include other script files ## Project Structure -- **Prima.Network**: Core networking components, packet definitions, serializers, and protocol implementations -- **Prima.Server**: Main server application handling game state, world simulation, and client connections -- **Prima.Tests**: Comprehensive test suite ensuring reliability and correctness - -## Features - -- **Modern C# Implementation**: Built with the latest C# features and .NET 9 -- **High Performance**: Optimized for efficiency with modern hardware -- **Extensible Architecture**: Modular design allowing for easy customization -- **Protocol Compatibility**: Full support for the UO network protocol -- **Containerization Ready**: Docker support for easy deployment -- **Comprehensive Testing**: Thorough test coverage for reliability - -## Development Status - -Prima is currently in early development. The networking layer and packet structures are being implemented, with core game functionality to follow. +- **Prima.Core.Server**: Core server infrastructure +- **Prima.Network**: Network layer and packet handling +- **Prima.Server**: Main server application +- **Prima.UOData**: Ultima Online data structures and utilities +- **Prima.Tcp.Test**: TCP testing utilities ## Getting Started ### Prerequisites -- .NET 9 SDK -- Docker (optional, for containerized deployment) - -### Building the Project - -```bash -dotnet build +- .NET 9.0 SDK +- Ultima Online client files for data loading + +### Configuration + +Configuration is handled through YAML files located in the `configs` directory: + +```yaml +Prima: + Server: + Shard: + Name: "Prima Shard" + UoDirectory: "/path/to/uo/files" + MaxPlayers: 1000 + TcpServer: + Host: "" + LoginPort: 2593 + GamePort: 2592 + EnableWebServer: true + WebServerPort: 23000 + LogPackets: true ``` -### Running Tests +### Building from Source ```bash -dotnet test +git clone https://github.com/tgiachi/prima.git +cd prima +dotnet build ``` ### Running the Server ```bash -dotnet run --project src/Prima.Server/Prima.Server.csproj +cd src/Prima.Server +dotnet run ``` ### Docker Support -Build the Docker image: +A Dockerfile is provided to build and run the server in a container: ```bash -docker build -t prima-server -f src/Prima.Server/Dockerfile . +docker build -t primauo/server . +docker run -p 2593:2593 -p 2592:2592 -p 23000:23000 -v /path/to/uo/files:/app/data/client primauo/server ``` -Run the container: +## API Documentation -```bash -docker run -p 2593:2593 prima-server +The server includes a Swagger UI for API documentation available at: + +``` +http://localhost:23000/swagger ``` ## Contributing -Contributions are welcome! If you'd like to contribute, please: +Contributions are welcome! Please feel free to submit a Pull Request. 1. Fork the repository -2. Create a feature branch -3. Submit a pull request +2. Create your feature branch (`git checkout -b feature/amazing-feature`) +3. Commit your changes (`git commit -m 'Add some amazing feature'`) +4. Push to the branch (`git push origin feature/amazing-feature`) +5. Open a Pull Request ## License @@ -92,10 +171,6 @@ This project is licensed under the MIT License - see the LICENSE file for detail ## Acknowledgments -- The Ultima Online team for creating a groundbreaking MMORPG -- The open-source community for their invaluable tools and libraries -- All contributors to the project - ---- - -*Prima is not affiliated with Electronic Arts or the official Ultima Online game. This is a fan project created to explore modern game server implementations while honoring the legacy of Ultima Online.* +- The Ultima Online community +- [ModernUO](https://github.com/modernuo/modernuo) for inspiration and some utility code +- [Orion](https://github.com/tgiachi/orion) for the server foundation framework