Bannou Service

Bannou is a schema-driven monoservice platform for multiplayer games. It provides a WebSocket-first edge gateway with zero-copy message routing, plugin-based service architecture, and abstracted infrastructure (lib-state, lib-messaging, lib-mesh). Designed to support Arcadia, a revolutionary MMORPG with 100,000+ AI-driven NPCs, Bannou scales from a single development machine to distributed production clusters without code changes.

Quick Start

# 1. Clone
git clone https://github.com/beyond-immersion/bannou-service.git
cd bannou-service

# 2. Install dev tools (.NET 10, NSwag, Python, Node.js)
./scripts/install-dev-tools.sh
source ~/.bashrc

# 3. Build and verify
make quick

# 4. Start the stack
make up-compose

# 5. Verify it's running
curl http://localhost:8080/health

Next steps: See the Quickstart Guide for client/service integration, or the Getting Started Guide for a comprehensive walkthrough.

Documentation

Getting Started

I want to...	Time	Guide
Get running quickly	5 min	Quickstart
Full setup walkthrough	30 min	Getting Started
Connect a game client	15 min	Client Integration
Make service-to-service calls	10 min	SDKs Overview

Development

I want to...	Read...
Understand the architecture	Bannou Design
Add or extend a plugin	Plugin Development Guide
Understand a specific service	Plugin Deep-Dives (41 services)
Run and write tests	Testing Guide
Contribute code	Development Rules

Operations

I want to...	Read...
Deploy to production	Deployment Guide
Understand CI/CD pipelines	GitHub Actions
Set up NuGet publishing	NuGet Setup

Key Features

• WebSocket-First: Connect service edge gateway with 31-byte binary headers for zero-copy routing
• Schema-Driven: OpenAPI specs generate controllers, models, clients, and tests—you write only 18-35% of the code
• Plugin Architecture: Each service is an independent assembly, loadable via environment config
• Infrastructure Abstraction: Portable infrastructure (databases, messaging, service mesh) via lib-state, lib-messaging, and lib-mesh
• Monoservice Flexibility: Same binary deploys as monolith or distributed microservices

Essential Commands

# Development
make build                 # Build all projects
make generate              # Regenerate services from schemas
make format                # Fix formatting and line endings

# Testing
make test                  # All unit tests
make test-http             # HTTP integration tests
make test-edge             # WebSocket edge tests
make test-ci               # Full CI pipeline locally

# Docker
make up-compose            # Start local stack
make down-compose          # Stop and cleanup

Technical Specifications

• WebSocket Protocol - Binary protocol specification
• Schema Rules - OpenAPI schema authoring reference
• Permissions System - Role-based access control schema
• Service Details - Service descriptions and API endpoints
• Events Reference - Auto-generated event documentation
• Configuration Reference - Environment variables
• State Stores - Redis/MySQL state stores

Project Structure

bannou-service/
├── schemas/              # OpenAPI specifications (source of truth)
├── plugins/lib-*/        # Service plugins (41 services)
├── bannou-service/       # Main application and shared code
├── sdks/                 # SDK packages (C#, TypeScript, Unreal)
│   ├── core/             # Shared types (BannouJson, ApiException, base events)
│   ├── server/           # Server SDK (mesh clients, behavior runtime)
│   ├── client/           # Client SDK (WebSocket, typed proxies, events)
│   ├── client-voice/     # Voice communication SDK
│   ├── bundle-format/    # .bannou archive format (LZ4 compression)
│   ├── asset-*/          # Asset loading/bundling (client, server, Stride, Godot)
│   ├── scene-composer-*/ # Scene composition (core, Stride, Godot)
│   ├── music-*/          # Music generation (theory, storyteller)
│   ├── typescript/       # TypeScript client SDK
│   └── unreal/           # Unreal Engine integration
├── tools/                # Testing and inspection tools
│   ├── http-tester/      # HTTP integration test framework
│   ├── edge-tester/      # WebSocket edge test framework
│   └── bannou-inspect/   # Assembly inspection CLI
├── examples/             # Example projects and demos
├── docs/                 # Documentation
├── provisioning/         # Docker and deployment configs
└── scripts/              # Code generation and build scripts

Community

• Discord: Beyond Immersion - Discussion, questions, and collaboration
• GitHub Issues: Bug reports and feature requests
• GitHub Discussions: Questions and broader conversations

Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

Please note that this project follows a Code of Conduct.

License

This project is licensed under the MIT License.